DVX BASIC IDE Guide
-DVX BASIC IDE Guide
DVX BASIC is a Visual BASIC development environment for the DVX GUI System. It provides a VB3-style integrated development environment with a code editor, form designer, project system, and a full interactive debugger -- all running natively on DOS under the DVX windowing system.
This guide covers every feature of the IDE: menus, toolbar, editor, form designer, project management, debugger, and auxiliary windows.
-IDE 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. @@ -613,7 +612,6 @@ img { max-width: 100%; }
Toolbar
-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
+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
+Run Group
Button Shortcut Action ------ -------- ------ Run F5 Compile and run the program. Stop Esc Stop the running program.-
Debug Group
+Debug Group
Button Shortcut Action
------ -------- ------
Debug Shift+F5 Start or resume a debug session.
@@ -750,7 +741,7 @@ img { max-width: 100%; }
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
+View Group
Button Shortcut Action
------ -------- ------
Code F7 Switch to Code view.
@@ -759,16 +750,15 @@ img { max-width: 100%; }
Code Editor
-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
+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
+Syntax Highlighting
The editor applies real-time syntax coloring as you type. The following categories are highlighted in distinct colors:
Category Examples
-------- --------
@@ -778,7 +768,7 @@ img { max-width: 100%; }
Comments ' This is a comment, REM This is a comment
Numbers 42, 3.14
Operators =, <, >, +, -, *, /, \, &
-Editor Features
+Editor Features
- Line numbers -- displayed in the gutter on the left side.
- Auto-indent -- new lines are automatically indented to match the previous line. @@ -790,9 +780,8 @@ img { max-width: 100%; }
Form Designer
-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
+Design Surface
- Grid snapping -- controls snap to an 8-pixel grid (DSGN_GRID_SIZE) when placed or resized.
- Selection -- click a control to select it. The selected control is highlighted with grab handles. @@ -802,7 +791,7 @@ img { max-width: 100%; }
- 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
+Form Properties
Forms have the following design-time properties: Name, Caption, Width, Height, Left, Top, Layout (VBox or HBox), Centered, AutoSize, and Resizable.
@@ -810,8 +799,7 @@ img { max-width: 100%; }Project System
-Project System
-Project Files (.dbp)
+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). @@ -819,9 +807,9 @@ img { max-width: 100%; }
- Metadata -- Author, Company, Version, Copyright, Description, and Icon Path (for compiled binaries).
File list -- relative paths (8.3 DOS names) of all .bas and .frm files in the project. Each entry tracks whether it is a form file.
-Source Map
+Source Map
When the project is compiled, all files are concatenated into a single source stream. A source map tracks which lines belong to which file, enabling accurate error reporting and debugger navigation across multiple files. For .frm files, an injected BEGINFORM directive is prepended to the code section.
-Project Operations
+Project Operations
Operation Description
--------- -----------
New Project Creates a blank project with a name and directory. A default .frm file is added automatically.
@@ -831,13 +819,12 @@ img { max-width: 100%; }
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
+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.
Properties Panel
-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. @@ -849,10 +836,9 @@ img { max-width: 100%; }
Toolbox
-Toolbox
The Toolbox (Window > Toolbox) is a floating palette of buttons, one for each available control type. Controls are loaded dynamically from the widget plugin registry -- any widget DXE that provides a basName 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
+Available Controls
VB Name Description
------- -----------
CommandButton Push button that triggers a Click event.
@@ -892,26 +878,25 @@ img { max-width: 100%; }
Debugger
-Debugger
The DVX BASIC IDE includes a full interactive debugger. The debugger operates as a state machine with three states:
State Description ----- ----------- DBG_IDLE No program loaded or running. DBG_RUNNING Program is executing (VM running in slices). DBG_PAUSED Execution is paused at a breakpoint or step point. The IDE GUI is fully interactive.-
Starting a Debug Session
+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
+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
+Breakpoint Validation
Not every line can have a breakpoint. The IDE validates the line content and silently refuses to set breakpoints on:
- Blank lines @@ -919,23 +904,23 @@ img { max-width: 100%; }
- SUB and FUNCTION declaration lines
END SUB and END FUNCTION lines
-Breakpoint Storage
+Breakpoint Storage
Each breakpoint records the project file index, the code line number within the file, the procedure index, and the procedure name (as Object.Event). When the project is compiled, breakpoints are converted to concatenated source line numbers that match the VM's OP_LINE opcodes.
-Visual Indicators
+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
+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
+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.-
The Debug Run Loop
+The Debug Run Loop
When a program is running in debug mode, the IDE enters a cooperative loop:
- The VM executes up to 10,000 steps per slice. @@ -943,7 +928,7 @@ img { max-width: 100%; }
- While paused, the IDE pumps dvxUpdate() continuously, keeping the GUI responsive. The user can inspect variables, modify them in the Immediate window, step, continue, or stop.
When the user resumes (F5/Shift+F5/F8/etc.), the state transitions back to DBG_RUNNING and the loop continues.
-Stopping
+Stopping
Press Esc or click the Stop toolbar button at any time to halt execution. The VM is destroyed, debug state resets to DBG_IDLE, and the IDE restores the designer windows that were hidden at run start.
@@ -953,7 +938,6 @@ img { max-width: 100%; }Locals Window
-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
@@ -973,7 +957,6 @@ img { max-width: 100%; }
Call Stack Window
-Call Stack Window
Shows the current call chain as a two-column ListView:
Column Content
------ -------
@@ -985,15 +968,14 @@ img { max-width: 100%; }
Watch Window
-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
+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 Expression Syntax
Watch expressions support:
- Simple variable names: x, count @@ -1002,7 +984,7 @@ img { max-width: 100%; }
- Combined: items(i).price
Arbitrary BASIC expressions (compiled and evaluated against the paused VM's state): x + y * 2, Len(name$)
-Editing and Deleting
+Editing and Deleting
- Double-click or press Enter on a watch entry to move it back into the input box for editing.
Breakpoints Window
-Breakpoints Window
Lists all set breakpoints as a three-column ListView:
Column Content
------ -------
@@ -1028,9 +1009,8 @@ img { max-width: 100%; }
Immediate Window
-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
+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:
-
@@ -1039,9 +1019,9 @@ img { max-width: 100%; }
LET x = 42 -- explicit assignment (see below).
Parse or runtime errors are displayed inline with an Error: prefix.
-Inspecting Variables While Paused
+Inspecting Variables While Paused
When the debugger is paused at a breakpoint, the Immediate window has access to the running VM's state. Global variable values are copied into the evaluation VM, so expressions like count or name$ & " test" display live values.
-Assigning Variables While Paused
+Assigning Variables While Paused
When paused, you can modify variables in the running program directly from the Immediate window using assignment syntax:
variableName = newValueThe optional LET keyword is also accepted:
@@ -1059,7 +1039,6 @@ img { max-width: 100%; }Output Window
-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. @@ -1072,9 +1051,8 @@ img { max-width: 100%; }
Find / Replace
-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
+Dialog Controls
Control Description
------- -----------
Find input The text to search for.
@@ -1082,29 +1060,28 @@ img { max-width: 100%; }
Scope Radio group: Function, Object, File, or Project. Default is Project.
Direction Radio group: Forward or Backward.
Match Case Checkbox: case-sensitive search.
-Buttons
+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
+Keyboard Shortcut
F3 repeats the last search (Find Next) without opening the dialog.
Preferences
-Preferences
Open via Tools > Preferences. Settings are saved to dvxbasic.ini in the app's config directory.
-Editor Section
+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, variables must be declared with DIM before use. Off Tab width Number of spaces per tab stop (1-8). 3 Insert spaces instead of tabs When enabled, pressing Tab inserts spaces. When disabled, inserts a real tab character. On-
New Project Defaults Section
+New Project Defaults Section
These fields set the default values for new project metadata:
Field Description Default
----- ----------- -------
@@ -1117,7 +1094,6 @@ img { max-width: 100%; }
Keyboard Shortcuts
-Keyboard Shortcuts
Shortcut Action
-------- ------
Ctrl+O Add File
@@ -1147,9 +1123,8 @@ img { max-width: 100%; }
Data Types
-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
+Primary Types
Type Size Suffix Range / Description
---- ---- ------ -------------------
Integer 2 bytes % -32768 to 32767
@@ -1158,7 +1133,7 @@ img { max-width: 100%; }
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
+Internal Types
These types are not directly declarable but are used internally by the runtime.
Internal Type Description
------------- -----------
@@ -1166,14 +1141,14 @@ img { max-width: 100%; }
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
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" ' StringNumeric Literals
+Numeric Literals
Form Example Description ---- ------- ----------- Decimal integer 42 Values -32768..32767 are Integer; larger are Long @@ -1182,13 +1157,12 @@ name$ = "Hello" ' StringFloating-point 3.14, 1.5E10 Double by default Single suffix 3.14! Force Single type Double suffix 3.14# Force Double type -
Type Promotion
+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$).
Operators
-Operators
Operators listed from highest precedence (evaluated first) to lowest precedence (evaluated last).
Precedence Operator Description ---------- -------- ----------- @@ -1204,14 +1178,13 @@ name$ = "Hello" ' String10 OR Logical/bitwise OR 11 EQV Logical/bitwise equivalence 12 (lowest) IMP Logical/bitwise implication -
String Concatenation
+String Concatenation
Use & to concatenate strings. The + operator also concatenates when both operands are strings.
result$ = "Hello" & " " & "World"
result$ = firstName$ & " " & lastName$Statements Overview
-Statements
+Statements
Multiple statements can appear on one line separated by :. Lines can be continued with _ at the end. Comments start with ' or REM.
@@ -1223,8 +1196,7 @@ result$ = firstName$ & " " & lastName$Declaration Statements
-Declaration Statements
-DIM
+DIM
Declares variables and arrays with an explicit type.
DIM variable AS type
DIM variable(upperBound) AS type
@@ -1242,20 +1214,20 @@ Dim Shared globalFlag As Boolean
Dim record As PersonType
Dim fixedStr As String * 20Note: DIM SHARED makes a variable accessible from all procedures without passing it as a parameter.-
REDIM
+REDIM
Reallocates a dynamic array, optionally preserving existing data.
REDIM array(newBounds) AS type
REDIM PRESERVE array(newBounds) AS typeReDim items(newSize) As String
ReDim Preserve scores(1 To newCount) As IntegerCONST
+CONST
Declares a named constant. The value must be a literal (integer, float, string, or boolean).
CONST name = valueConst MAX_SIZE = 100
Const PI = 3.14159265
Const APP_NAME = "DVX App"
Const DEBUG_MODE = TrueTYPE...END TYPE
+TYPE...END TYPE
Defines a user-defined type (record/structure).
TYPE TypeName
fieldName AS type
@@ -1271,11 +1243,11 @@ Dim p As PersonType
p.firstName = "Scott"
p.age = 30UDT fields can themselves be UDTs (nested types).
-DECLARE
+DECLARE
Forward-declares a SUB or FUNCTION. Required when a procedure is called before it is defined.
DECLARE SUB name ([BYVAL] param AS type, ...)
DECLARE FUNCTION name ([BYVAL] param AS type, ...) AS returnTypeDECLARE LIBRARY
+DECLARE LIBRARY
Declares external native functions from a dynamically loaded library. This allows BASIC programs to call functions exported by DXE libraries.
DECLARE LIBRARY "libraryName"
DECLARE SUB name ([BYVAL] param AS type, ...)
@@ -1286,7 +1258,7 @@ END DECLARESTATIC
+STATIC
Declares a local variable that retains its value between calls.
STATIC variable AS typeSub Counter()
@@ -1294,14 +1266,14 @@ End DeclareOPTION
+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 DIMDEFtype Statements
+DEFtype Statements
Set the default type for variables based on their first letter.
DEFINT letterRange
DEFLNG letterRange
@@ -1310,30 +1282,29 @@ DEFDBL letterRange
DEFSTR letterRangeDefInt I-N ' Variables starting with I through N default to Integer
DefStr S ' Variables starting with S default to StringAssignment
+Assignment
Assigns a value to a variable, array element, or UDT field.
variable = expression
array(index) = expression
udt.field = expression
LET variable = expressionThe LET keyword is optional and supported for compatibility.
-SWAP
+SWAP
Exchanges the values of two variables.
SWAP variable1, variable2Swap a, bERASE
+ERASE
Frees the memory of an array and resets it.
ERASE arrayNameConditional Statements
-Conditional Statements
-IF...THEN...ELSE...END IF
+IF...THEN...ELSE...END IF
Conditional execution. Supports single-line and multi-line forms.
-Single-line form
+Single-line form
IF condition THEN statement
IF condition THEN statement ELSE statementMulti-line form
+Multi-line form
IF condition THEN
statements
ELSEIF condition THEN
@@ -1350,7 +1321,7 @@ Else
End If
If ready Then Print "Go!"SELECT CASE
+SELECT CASE
Multi-way branch based on an expression value.
SELECT CASE expression
CASE value
@@ -1380,8 +1351,7 @@ End SelectLoop Statements
-Loop Statements
-FOR...NEXT
+FOR...NEXT
Counted loop with an optional step value.
FOR variable = start TO limit [STEP step]
statements
@@ -1394,7 +1364,7 @@ For x = 10 To 0 Step -2
Print x
NextThe variable name after NEXT is optional. Use EXIT FOR to break out early.
-DO...LOOP
+DO...LOOP
General-purpose loop with pre-test, post-test, or infinite forms.
DO [WHILE condition | UNTIL condition]
statements
@@ -1414,7 +1384,7 @@ Do
DoEvents
If done Then Exit Do
LoopWHILE...WEND
+WHILE...WEND
Simple pre-test loop (legacy form; prefer DO...LOOP).
WHILE condition
statements
@@ -1426,8 +1396,7 @@ WendProcedures
-Procedures
-SUB...END SUB
+SUB...END SUB
Defines a subroutine (no return value).
SUB name ([BYVAL] param AS type, ...)
statements
@@ -1436,7 +1405,7 @@ END SUBParameters are passed ByRef by default. Use ByVal for value semantics. Use EXIT SUB to return early.
-FUNCTION...END FUNCTION
+FUNCTION...END FUNCTION
Defines a function with a return value.
FUNCTION name ([BYVAL] param AS type, ...) AS returnType
statements
@@ -1446,7 +1415,7 @@ END FUNCTIONAssign to the function name to set the return value. Use EXIT FUNCTION to return early.
-DEF FN
+DEF FN
Defines a single-expression function.
DEF FNname(params) = expressionDef FnSquare(x) = x * x
@@ -1454,19 +1423,18 @@ Print FnSquare(5) ' prints 25Flow Control
-Flow Control
-EXIT
+EXIT
Exits the current block early.
EXIT FOR
EXIT DO
EXIT SUB
EXIT FUNCTIONCALL
+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 / GOSUB / RETURN
GOTO label
GOSUB label
RETURNON...GOTO / ON...GOSUB
+ON...GOTO / ON...GOSUB
Computed branch based on an integer expression.
ON expression GOTO label1, label2, ...
ON expression GOSUB label1, label2, ...Input/Output Statements
-Input/Output Statements
-Outputs text to the console or to a file channel.
PRINT [expression] [{; | ,} expression] ...
PRINT #channel, expression
@@ -1507,14 +1474,14 @@ PRINT USING format$; expression [; expression] ...Print "Name:"; Tab(20); name$
Print Using "###.##"; total
Print #1, "Written to file"INPUT
+INPUT
Reads a line of text from the user or from a file channel.
INPUT variable
INPUT "prompt"; variable
INPUT #channel, variableInput "Enter your name: "; name$
Input #1, line$DATA / READ / RESTORE
+DATA / READ / RESTORE
Inline data pool for constants.
DATA value1, value2, "string", ...
READ variable1, variable2, ...
@@ -1527,8 +1494,7 @@ RestoreMiscellaneous Statements
-Miscellaneous Statements
-Error Handling
+Error Handling
ON ERROR GOTO label ' Enable error handler
ON ERROR GOTO 0 ' Disable error handler
RESUME ' Retry the statement that caused the error
@@ -1542,27 +1508,26 @@ Exit Sub
ErrorHandler:
Print "Error number:"; Err
Resume NextSHELL
+SHELL
Executes an operating system command.
SHELL "command"When used as a function, returns the exit code of the command.
Shell "DIR /B"
exitCode = Shell("COPY A.TXT B.TXT")SLEEP
+SLEEP
Pauses execution for a specified number of seconds.
SLEEP secondsRANDOMIZE
+RANDOMIZE
Seeds the random number generator.
RANDOMIZE seed
RANDOMIZE TIMER ' Seed from system clockEND
+END
Terminates program execution immediately.
ENDFile I/O
-File I/O
-OPEN
+OPEN
Opens a file for reading, writing, or appending.
OPEN filename$ FOR INPUT AS #channel
OPEN filename$ FOR OUTPUT AS #channel
@@ -1576,35 +1541,34 @@ OPEN filename$ FOR BINARY AS #channelCLOSE
+CLOSE
Closes an open file channel.
CLOSE #channelPRINT #
+PRINT #
Writes text to a file.
PRINT #channel, expressionINPUT #
+INPUT #
Reads comma-delimited data from a file.
INPUT #channel, variableLINE INPUT #
+LINE INPUT #
Reads an entire line from a file into a string variable.
LINE INPUT #channel, variable$WRITE #
+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.14GET / PUT
+GET / PUT
Read and write records in RANDOM or BINARY mode files.
GET #channel, [recordNum], variable
PUT #channel, [recordNum], variableSEEK
+SEEK
Sets the file position. As a function, returns the current position.
SEEK #channel, position ' Statement: set position
pos = SEEK(channel) ' Function: get current positionString Functions
-String Functions
Function Returns Description -------- ------- ----------- ASC(s$) Integer ASCII code of first character of s$ @@ -1626,13 +1590,12 @@ pos = SEEK(channel) ' Function: get current positionTRIM$(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 -
MID$ Assignment
+MID$ Assignment
MID$ can also be used on the left side of an assignment to replace a portion of a string:
Mid$(s$, 3, 2) = "XY" ' Replace 2 characters starting at position 3Math Functions
-Math Functions
Function Returns Description -------- ------- ----------- ABS(n) Double Absolute value of n @@ -1652,7 +1615,6 @@ pos = SEEK(channel) ' Function: get current position
Conversion Functions
-Conversion Functions
Function Returns Description -------- ------- ----------- CDBL(n) Double Converts n to Double @@ -1663,7 +1625,6 @@ pos = SEEK(channel) ' Function: get current position
File I/O Functions
-File I/O Functions
Function Returns Description -------- ------- ----------- EOF(channel) Boolean True if file pointer is at end of file @@ -1677,7 +1638,6 @@ pos = SEEK(channel) ' Function: get current position
Miscellaneous Functions
-Miscellaneous Functions
Function Returns Description -------- ------- ----------- DATE$ String Current date as "MM-DD-YYYY" @@ -1687,13 +1647,12 @@ pos = SEEK(channel) ' Function: get current position
Form and Control Statements
-Form and Control Statements
DVX BASIC supports Visual Basic-style forms and controls for building graphical user interfaces. Forms are defined in .frm files and loaded at runtime.
-Loading and Unloading Forms
+Loading and Unloading Forms
LOAD FormName
UNLOAD FormNameLOAD creates the form and its controls in memory. UNLOAD destroys the form and frees its resources.
-Showing and Hiding Forms
+Showing and Hiding Forms
FormName.Show [modal]
FormName.Hide
Me.Show [modal]
@@ -1701,35 +1660,35 @@ Me.HidePass vbModal (1) to Show for a modal dialog.
Form2.Show vbModal
Me.HideProperty Access
+Property Access
Read and write control properties using dot notation:
ControlName.Property = value
value = ControlName.PropertyText1.Text = "Hello"
label1.Caption = "Name: " & name$
x = Text1.LeftMethod Calls
+Method Calls
ControlName.Method [args]List1.AddItem "New entry"
List1.ClearMe Keyword
+Me Keyword
Me refers to the current form. Use it to access the form's own properties, controls, and methods from within event handlers.
Me.Caption = "Updated Title"
Me.Text1.Text = ""
Me.HideControl Arrays
+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 = TrueDoEvents
+DoEvents
Yields control to the DVX event loop, allowing the GUI to process pending events. Call this in long-running loops to keep the UI responsive.
DOEVENTSFor i = 1 To 10000
' process data
If i Mod 100 = 0 Then DoEvents
NextMsgBox
+MsgBox
Displays a message box dialog. Can be used as a statement (discards result) or as a function (returns the button clicked).
MSGBOX message$ [, flags]
result = MSGBOX(message$ [, flags])InputBox$
+InputBox$
Displays an input dialog and returns the user's text entry.
result$ = INPUTBOX$(prompt$ [, title$ [, default$]])name$ = InputBox$("Enter your name:", "Name Entry", "")Event Handler Convention
+Event Handler Convention
Event handlers are named ControlName_EventName and defined as SUBs:
Sub Command1_Click()
MsgBox "Button clicked!"
@@ -1755,7 +1714,7 @@ End Sub
Sub Text1_Change()
Label1.Caption = "You typed: " & Text1.Text
End SubCommon Events
+Common Events
Event Description ----- ----------- Click Control was clicked @@ -1776,64 +1735,63 @@ End Sub
SQL Functions
-SQL Functions
DVX BASIC includes built-in SQLite database support through a set of SQL functions. All functions use database handles and result set handles (integers) returned by SQLOpen and SQLQuery.
-Opening and Closing Databases
-SQLOpen
+Opening and Closing Databases
+SQLOpen
Opens a SQLite database file and returns a database handle.
db = SQLOPEN(path$)db = SQLOpen(App.Data & "\mydata.db")SQLClose
+SQLClose
Closes an open database.
SQLCLOSE dbExecuting SQL
-SQLExec
+Executing SQL
+SQLExec
Executes a SQL statement that does not return data (INSERT, UPDATE, DELETE, CREATE TABLE, etc.). Can be used as a statement or as a function returning a Boolean success flag.
SQLEXEC db, sql$
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
+SQLAffected
Returns the number of rows affected by the last INSERT, UPDATE, or DELETE.
count = SQLAFFECTED(db)Querying Data
-SQLQuery
+Querying Data
+SQLQuery
Executes a SELECT query and returns a result set handle.
rs = SQLQUERY(db, sql$)rs = SQLQuery(db, "SELECT id, name FROM users ORDER BY name")SQLNext
+SQLNext
Advances to the next row in the result set. Can be used as a statement or as a function returning True if a row is available.
SQLNEXT rs
hasRow = SQLNEXT(rs)SQLEof
+SQLEof
Returns True if there are no more rows in the result set.
done = SQLEOF(rs)Reading Fields
-SQLField$
+Reading Fields
+SQLField$
Returns a field value as a string. The field can be specified by column index (0-based) or by column name.
value$ = SQLFIELD$(rs, columnIndex)
value$ = SQLFIELD$(rs, "columnName")name$ = SQLField$(rs, "name")
first$ = SQLField$(rs, 0)SQLFieldInt
+SQLFieldInt
Returns a field value as an integer.
value = SQLFIELDINT(rs, columnIndex)SQLFieldDbl
+SQLFieldDbl
Returns a field value as a double.
value# = SQLFIELDDBL(rs, columnIndex)SQLFieldCount
+SQLFieldCount
Returns the number of columns in the result set.
count = SQLFIELDCOUNT(rs)Result Set Cleanup
-SQLFreeResult
+Result Set Cleanup
+SQLFreeResult
Frees a result set. Always call this when done iterating a query.
SQLFREERESULT rsError Information
-SQLError$
+Error Information
+SQLError$
Returns the last error message for the database.
msg$ = SQLERROR$(db)Complete SQL Example
+Complete SQL Example
Dim db As Long
Dim rs As Long
@@ -1851,7 +1809,6 @@ SQLClose dbApp Object
-App Object
The App object provides read-only properties for the application's directory paths.
Property Returns Description -------- ------- ----------- @@ -1864,14 +1821,13 @@ Print "Running from: " & App.Path
INI Functions
-INI Functions
DVX BASIC provides built-in functions for reading and writing standard INI configuration files.
-IniRead
+IniRead
Reads a value from an INI file. Returns the default value if the key is not found.
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
+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"
@@ -1879,9 +1835,8 @@ IniWrite App.Config & "\app.ini", "Display", "FontS
Predefined Constants
-Predefined Constants
The following constants are predefined by the compiler and available in all programs.
-MsgBox Button Style Flags
+MsgBox Button Style Flags
Constant Value Description -------- ----- ----------- vbOKOnly 0 OK button only (default) @@ -1889,7 +1844,7 @@ IniWrite App.Config & "\app.ini", "Display", "FontS vbYesNo 2 Yes and No buttons vbYesNoCancel 3 Yes, No, and Cancel buttons vbRetryCancel 4 Retry and Cancel buttons-
MsgBox Icon Flags
+MsgBox Icon Flags
Add an icon flag to the button style to display an icon in the message box.
Constant Value Description -------- ----- ----------- @@ -1897,7 +1852,7 @@ IniWrite App.Config & "\app.ini", "Display", "FontS vbExclamation &H20 Warning icon vbCritical &H30 Error/critical icon vbQuestion &H40 Question mark icon-
MsgBox Return Values
+MsgBox Return Values
Constant Value Description -------- ----- ----------- vbOK 1 User clicked OK @@ -1905,11 +1860,11 @@ IniWrite App.Config & "\app.ini", "Display", "FontS vbYes 3 User clicked Yes vbNo 4 User clicked No vbRetry 5 User clicked Retry-
Show Mode Flags
+Show Mode Flags
Constant Value Description -------- ----- ----------- vbModal 1 Show form as modal dialog-
Boolean Constants
+Boolean Constants
Constant Value Description -------- ----- ----------- True -1 Boolean true @@ -1917,9 +1872,8 @@ IniWrite App.Config & "\app.ini", "Display", "FontS
Common Properties, Events, and Methods
-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
+Common Properties
Property Type R/W Description ---------- ------- --- ------------------------------------------- Name String R The control's name (e.g. "Command1"). Read-only at runtime. @@ -1937,7 +1891,7 @@ IniWrite App.Config & "\app.ini", "Display", "FontS 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
+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 --------- ------------------------------------------- ------------------------------------------- @@ -1953,7 +1907,7 @@ IniWrite App.Config & "\app.ini", "Display", "FontS 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
+Common Methods
Method Parameters Description -------- ---------- ------------------------------------------- SetFocus (none) Gives keyboard focus to this control. @@ -1964,13 +1918,12 @@ IniWrite App.Config & "\app.ini", "Display", "FontS
Data Binding
-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
+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. @@ -1978,16 +1931,16 @@ IniWrite App.Config & "\app.ini", "Display", "FontS
- 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
+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
+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
+Example
VERSION DVX 1.00
Begin Form frmData
Caption = "Data Binding Example"
@@ -2029,9 +1982,8 @@ End SubControl Arrays
-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
+Defining Control Arrays in FRM
Begin CommandButton Command1
Caption = "Button A"
Index = 0
@@ -2104,7 +2055,7 @@ Begin CommandButton Command1
Caption = "Button C"
Index = 2
EndEvent Handler Convention
+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
@@ -2116,7 +2067,7 @@ EndAccessing Array Elements in Code
+Accessing Array Elements in Code
Use the indexed form ControlName(Index) to access a specific element:
Command1(0).Caption = "New Text"
Command1(1).Enabled = FalseFRM 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
+Structure
VERSION DVX 1.00
Begin Form FormName
form-level properties...
@@ -2158,7 +2108,7 @@ BASIC code follows...
Sub FormName_Load ()
...
End SubRules
+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. @@ -2169,7 +2119,7 @@ End Sub
- Comments in the form section use ' (single quote).
Blank lines are ignored in the form section.
-Common FRM Properties
+Common FRM Properties
Property Applies To Description ----------------------- --------------- ------------------------------------------- Caption Form, controls Display text or window title. @@ -2199,10 +2149,9 @@ End Sub
Form
-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
+Form Properties
Property Type Default Description ---------- ------- -------------- ------------------------------------------- Name String "Form1" The form's name, used for event dispatch and Load statement. @@ -2215,7 +2164,7 @@ End SubAutoSize Boolean True 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
+Form Events
Event Parameters Description ----------- --------------------- ------------------------------------------- Load (none) Fires after the form and all controls are created. This is the default event. @@ -2224,7 +2173,7 @@ End SubResize (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
+Form Methods
Statement Description ------------------ ------------------------------------------- Load FormName Load the form (creates the window and controls, fires Load event). @@ -2232,7 +2181,7 @@ End SubFormName.Show Make the form visible. FormName.Show 1 Show as modal dialog (blocks until closed). FormName.Hide Hide the form without unloading it. -
Example
+Example
Sub Form_Load ()
Form1.Caption = "Hello World"
Print "Form loaded!"
@@ -2252,16 +2201,15 @@ End SubTerminal
-Terminal
DVX Extension -- DVX Widget: ansiterm (ANSI terminal emulator)
A VT100/ANSI terminal emulator widget. Supports ANSI escape sequences, scrollback buffer, and serial communication. Default size is 80 columns by 25 rows.
-Type-Specific Properties
+Type-Specific Properties
Property Type Description ---------- ------- ------------------------------------------- Cols Integer Number of character columns (read-only). Rows Integer Number of character rows (read-only). Scrollback Integer Number of scrollback lines (write-only).-
Type-Specific Methods
+Type-Specific Methods
Method Parameters Description ------ --------------- ------------------------------------------- Clear (none) Clear the terminal screen. @@ -2271,16 +2219,15 @@ End Sub
Frame
-Frame
VB Equivalent: Frame -- DVX Widget: frame (titled VBox 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
+Type-Specific Properties
Property Type Description -------- ------ ------------------------------------------- Caption String The title displayed in the frame border.
Container: Yes
Default Event: Click
-Example
+Example
Begin Frame Frame1
Caption = "Options"
Begin CheckBox Check1
@@ -2294,7 +2241,6 @@ EndHBox
-HBox
DVX Extension -- DVX Widget: hbox (horizontal layout container)
A container that arranges its children horizontally, left to right. Use Weight on children to distribute extra space.
Container: Yes
@@ -2305,7 +2251,6 @@ EndVBox
-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.
Container: Yes
@@ -2316,16 +2261,15 @@ EndCommandButton
-CommandButton
VB Equivalent: CommandButton -- DVX Widget: button | Name Prefix: Command
A push button that triggers an action when clicked. Created with wgtButton(parent, text).
-Type-Specific Properties
+Type-Specific Properties
Property Type Description -------- ------ ------------------------------------------- Caption String The text displayed on the button. Use & for accelerator keys (e.g. "&OK").
No additional type-specific properties beyond common properties and Caption.
Default Event: Click
-Example
+Example
Begin Form Form1
Caption = "Button Demo"
Begin CommandButton Command1
@@ -2340,10 +2284,9 @@ End SubPictureBox
-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.
-Type-Specific Methods
+Type-Specific Methods
Method Parameters Description ------ ---------------- ------------------------------------------- Clear Color As Integer Fill the entire canvas with the specified color.@@ -2353,16 +2296,15 @@ End Sub
CheckBox
-CheckBox
VB Equivalent: CheckBox -- DVX Widget: checkbox
A toggle control with a label. Checked state is exposed as a Boolean.
-Type-Specific Properties
+Type-Specific Properties
Property Type Description -------- ------- ------------------------------------------- Caption String The text displayed next to the checkbox. Value Boolean True if checked, False if unchecked.
Default Event: Click
-Example
+Example
Begin CheckBox Check1
Caption = "Enable feature"
End
@@ -2378,16 +2320,15 @@ End SubComboBox
-ComboBox
VB Equivalent: ComboBox -- DVX Widget: combobox (editable text field + drop-down list, max 256 chars)
A combination of a text input and a drop-down list. The user can type text or select from the list. Supports the same AddItem/RemoveItem/Clear/List methods as ListBox.
-Type-Specific Properties
+Type-Specific Properties
Property Type Description --------- ------- ------------------------------------------- Text String The text in the editable field. ListIndex Integer Index of the currently selected list item (-1 = none). ListCount Integer Number of items in the drop-down list (read-only).-
Type-Specific Methods
+Type-Specific Methods
Same as ListBox: AddItem, RemoveItem, Clear, List.
Default Event: Click
@@ -2395,11 +2336,10 @@ End SubData
-Data
VB Equivalent: Data -- DVX Widget: data (database record navigator)
A data access control that connects to a SQLite database and provides record navigation. Other controls can bind to a Data control via their DataSource and DataField properties.
-Type-Specific Properties
+Type-Specific Properties
Property Type R/W Description ------------ ------- --- ------------------------------------------- DatabaseName String R/W Path to the SQLite database file. @@ -2411,7 +2351,7 @@ End SubMasterSource String R/W Name of a master Data control (for master-detail binding). MasterField String R/W Column in the master recordset to filter by. DetailField String R/W Column in this recordset that matches the master field. -
Type-Specific Methods
+Type-Specific Methods
Method Parameters Description ------------ ---------- ------------------------------------------- MoveFirst (none) Navigate to the first record. @@ -2422,7 +2362,7 @@ End SubDelete (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
+Type-Specific Events
Event Parameters Description ---------- ----------------- ------------------------------------------- Reposition (none) Fires after the current record changes (navigation). This is the default event. @@ -2433,19 +2373,18 @@ End Sub
DBGrid
-DBGrid
VB Equivalent: DBGrid -- DVX Widget: dbgrid
A data-bound grid that displays records from a Data control in a tabular format. Columns are auto-generated from the query results. Bind it using the DataSource property.
-Type-Specific Properties
+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.-
Type-Specific Methods
+Type-Specific Methods
Method Parameters Description ------- ---------- ------------------------------------------- Refresh (none) Reload and redraw the grid from the Data control.-
Type-Specific Events
+Type-Specific Events
Event Parameters Description -------- ---------- ------------------------------------------- Click (none) Fires when a cell is clicked. @@ -2456,15 +2395,14 @@ End Sub
DropDown
-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.
-Type-Specific Properties
+Type-Specific Properties
Property Type Description --------- ------- ------------------------------------------- ListIndex Integer Index of the currently selected item. ListCount Integer Number of items (read-only).-
Type-Specific Methods
+Type-Specific Methods
Same as ListBox: AddItem, RemoveItem, Clear, List.
Default Event: Click
@@ -2472,10 +2410,9 @@ End SubImageButton
-ImageButton
DVX Extension -- DVX Widget: imagebutton
A button that displays an image instead of text. Like Image, it requires pixel data at creation time and is typically loaded via the Picture property.
-Type-Specific Properties
+Type-Specific Properties
Property Type Description ----------- ------- ------------------------------------------- Picture String Path to a BMP file to load (write-only). @@ -2486,10 +2423,9 @@ End Sub
Image
-Image
VB Equivalent: Image -- DVX Widget: image
A static image display control. Loads BMP images from file. Cannot be placed via the designer toolbox (requires pixel data at creation time); typically created in code or loaded via the Picture property.
-Type-Specific Properties
+Type-Specific Properties
Property Type Description ----------- ------- ------------------------------------------- Picture String Path to a BMP file to load (write-only). @@ -2500,16 +2436,15 @@ End Sub
Label
-Label
VB Equivalent: Label -- DVX Widget: label
A static text label. Supports left, center, and right alignment.
-Type-Specific Properties
+Type-Specific Properties
Property Type Description --------- ---- ------------------------------------------- Caption String The text displayed by the label. Alignment Enum Text alignment: Left (default), Center, or Right.
Default Event: Click
-Example
+Example
Begin Label Label1
Caption = "Hello, World!"
Alignment = "Center"
@@ -2518,15 +2453,14 @@ EndListBox
-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.
-Type-Specific Properties
+Type-Specific Properties
Property Type Description --------- ------- ------------------------------------------- ListIndex Integer Index of the currently selected item (-1 = no selection). ListCount Integer Number of items in the list (read-only).-
Type-Specific Methods
+Type-Specific Methods
Method Parameters Description --------------- --------------------------------------- ------------------------------------------- AddItem Text As String Add an item to the end of the list. @@ -2540,7 +2474,7 @@ EndIsItemSelected Index As Integer Returns True if the item at Index is selected. SetItemSelected Index As Integer, Selected As Boolean Select or deselect a specific item.
Default Event: Click
-Example
+Example
Sub Form_Load ()
List1.AddItem "Apple"
List1.AddItem "Banana"
@@ -2560,14 +2494,13 @@ End SubListView
-ListView
VB Equivalent: ListView -- DVX Widget: listview
A multi-column list with column headers. Supports sorting, multi-select, and drag-to-reorder. Columns are configured via the C API (SetColumns, SetData).
-Type-Specific Properties
+Type-Specific Properties
Property Type Description --------- ------- ------------------------------------------- ListIndex Integer Index of the currently selected row (-1 = none).-
Type-Specific Methods
+Type-Specific Methods
Method Parameters Description --------------- --------------------------------------- ------------------------------------------- SelectAll (none) Select all rows. @@ -2581,10 +2514,9 @@ End Sub
ProgressBar
-ProgressBar
VB Equivalent: ProgressBar -- DVX Widget: progressbar
A horizontal progress indicator bar.
-Type-Specific Properties
+Type-Specific Properties
Property Type Description -------- ------- ------------------------------------------- Value Integer Current progress value (0-100).@@ -2593,15 +2525,14 @@ End Sub
OptionButton
-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
+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
+Type-Specific Methods
Method Parameters Description ----------- ----------------- ------------------------------------------- SetSelected Index As Integer Select the radio button at the given index within the group.@@ -2610,10 +2541,9 @@ End Sub
ScrollPane
-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
+Type-Specific Properties
Property Type Description -------- ------- ------------------------------------------- NoBorder Boolean When True, suppresses the border around the scroll pane.@@ -2623,7 +2553,6 @@ End Sub
Line
-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.
@@ -2631,15 +2560,14 @@ End SubHScrollBar
-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
+Type-Specific Properties
Property Type Description -------- ------- ------------------------------------------- Value Integer The current slider position (clamped to min/max range).
Default Event: Change
-Example
+Example
Begin HScrollBar HScroll1
MinWidth = 200
End
@@ -2651,7 +2579,6 @@ End SubSpacer
-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.
@@ -2659,16 +2586,15 @@ End SubSpinButton
-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
+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
+Type-Specific Methods
Method Parameters Description -------- ------------------------------ ------------------------------------------- SetRange Min As Integer, Max As Integer Set the allowed value range. @@ -2678,10 +2604,9 @@ End Sub
Splitter
-Splitter
DVX Extension -- DVX Widget: splitter
A resizable split pane. Holds exactly two child widgets separated by a draggable divider. Default orientation is vertical (top/bottom split).
-Type-Specific Properties
+Type-Specific Properties
Property Type Description -------- ------- ------------------------------------------- Position Integer Position of the divider in pixels from the top (or left).@@ -2691,7 +2616,6 @@ End Sub
StatusBar
-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 accepts child widgets, but it is not registered as a container in the form runtime, so child controls cannot be nested inside it in .frm files. Set its Caption property to display status text.
No type-specific properties, events, or methods.
@@ -2699,14 +2623,13 @@ End SubTabStrip
-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
+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
+Type-Specific Methods
Method Parameters Description --------- ----------------- ------------------------------------------- SetActive Index As Integer 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).@@ -2717,17 +2640,16 @@ End Sub
TextBox
-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
+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
+Example
Begin TextBox Text1
Text = "Enter text here"
End
@@ -2740,10 +2662,9 @@ End SubTextArea
-TextArea
VB Equivalent: TextArea (DVX extension) -- DVX Widget: textarea (multi-line text input, max 4096 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 syntax colorization, line numbers, auto-indent, and find/replace via the C API.
-Type-Specific Properties
+Type-Specific Properties
Property Type Description -------- ------ ------------------------------------------- Text String The full text content.@@ -2752,25 +2673,24 @@ End Sub
Timer
-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
+Type-Specific Properties
Property Type Description -------- ------- ------------------------------------------- Enabled Boolean True to start the timer, False to stop it. Interval Integer Timer interval in milliseconds (write-only from BASIC).-
Type-Specific Methods
+Type-Specific Methods
Method Parameters Description ------ ---------- ------------------------------------------- Start (none) Start the timer. Stop (none) Stop the timer.-
Type-Specific Events
+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
+Example
Begin Timer Timer1
Interval = 1000
Enabled = True
@@ -2786,7 +2706,6 @@ End SubToolbar
-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
@@ -2795,10 +2714,9 @@ End SubTreeView
-TreeView
VB Equivalent: TreeView -- DVX Widget: treeview
A hierarchical tree of expandable/collapsible nodes. Nodes are created via the C API (wgtTreeItem). Supports multi-select and drag-to-reorder.
-Type-Specific Methods
+Type-Specific Methods
Method Parameters Description -------------- ---------------------- ------------------------------------------- SetMultiSelect Multi As Boolean Enable or disable multi-select mode. @@ -2808,10 +2726,9 @@ End Sub
WrapBox
-WrapBox
DVX Extension -- DVX Widget: 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
+Type-Specific Properties
Property Type Description --------- ---- ------------------------------------------- Alignment Enum Horizontal alignment of items: Left, Center, or Right.diff --git a/docs/dvx_help_viewer.html b/docs/dvx_help_viewer.html index 01e71c6..504c495 100644 --- a/docs/dvx_help_viewer.html +++ b/docs/dvx_help_viewer.html @@ -53,12 +53,11 @@ img { max-width: 100%; }
DVX Help Viewer
-DVX Help Viewer
The DVX Help Viewer displays .hlp help files compiled from .dhs source documents. It provides a tree-based table of contents, scrollable content with word-wrapped text, clickable hyperlinks, full-text search, and a keyword index.
-Opening Help
+Opening Help
Press F1 from any DVX application to open context-sensitive help. Applications can register their own help file and topic so F1 opens the relevant page.
You can also launch the help viewer from an application's Help menu, or by clicking the DVX Help icon in the Program Manager.
-Navigation
+Navigation
- Click a topic in the tree on the left to display it
- Click underlined links in the content to jump to other topics @@ -66,7 +65,7 @@ img { max-width: 100%; }
- Use Navigate > Index to browse an alphabetical keyword list
Use Navigate > Search to find topics by keyword
-Keyboard Shortcuts
+Keyboard Shortcuts
Alt+Left Back
Alt+Right Forward
Ctrl+F Search
@@ -74,21 +73,20 @@ img { max-width: 100%; }
Help Source Format (.dhs)
-Help Source Format (.dhs)
Help files are authored as plain text .dhs source files using a simple line-oriented directive format. Lines beginning with a period at column 0 are directives. All other lines are body text, which is automatically word-wrapped by the viewer at display time.
-Topic Directives
+Topic Directives
.topic <id> Start a new topic with a unique string ID .title <text> Set the topic's display title .toc <depth> <text> Add a table of contents entry (0=root, 1=child, etc.) .default Mark this topic as the one shown when the file opens-
Content Directives
+Content Directives
.h1 <text> Level 1 heading (colored bar) .h2 <text> Level 2 heading (underlined) .h3 <text> Level 3 heading (plain) .hr Horizontal rule .link <id> <text> Hyperlink to another topic .image <file.bmp> Inline image (BMP format)-
Block Directives
+Block Directives
.list Start a bulleted list
.item <text> List item (must be inside .list)
.endlist End the bulleted list
@@ -98,9 +96,9 @@ img { max-width: 100%; }
.endcode End code block
.note [info|tip|warning] Start a callout box
.endnote End callout box
-Index Directives
+Index Directives
.index <keyword> Add a keyword to the index pointing to this topic-
Example
+Example
.topic intro
.title Welcome
.toc 0 Welcome
@@ -130,7 +128,7 @@ This is a helpful tip.
.note warning
This is a warning message.
.endnoteCallout Boxes
+Callout Boxes
Three types of callout boxes are available, each with a distinct colored accent bar:
Note: Use info notes for general supplementary information.
Tip: Use tip notes for helpful suggestions and best practices.@@ -138,35 +136,33 @@ This is a warning message.
Help Compiler (dvxhlpc)
-Help Compiler (dvxhlpc)
The dvxhlpc tool runs on the host (Linux) and compiles .dhs source files into binary .hlp files for the viewer, and optionally into self-contained HTML.
-Usage
+Usage
dvxhlpc -o output.hlp [-i imagedir] [--html out.html] input.dhs [...]Options
+Options
-o output.hlp Output binary help file (required) -i imagedir Directory to find .image files (default: current dir) --html out.html Also emit a self-contained HTML file
Multiple input files are merged into a single help file. This allows per-widget or per-feature documentation fragments to be combined automatically.
-Build Integration
+Build Integration
The standard build pattern globs all fragments:
dvxhlpc -o dvxhelp.hlp docs/src/overview.dhs widgets/*/*.dhsNew widgets or features just drop a .dhs file in their source directory and it appears in the help on the next build.
-HTML Output
+HTML Output
The --html flag produces a single self-contained HTML file with a sidebar table of contents, styled headings, lists, code blocks, notes, and embedded images (base64 data URIs). This is useful for viewing documentation on the host machine without running the DOS help viewer.
Application Integration
-Application Integration
Any DVX application can provide context-sensitive help via the F1 key.
-Setting Up Help
+Setting Up Help
In your appMain, set the help file path on the app context:
snprintf(ctx->helpFile, sizeof(ctx->helpFile),
"%s%cMYAPP.HLP", ctx->appDir, DVX_PATH_SEP);Context-Sensitive Topics
+Context-Sensitive Topics
Update helpTopic as the user navigates your application:
snprintf(ctx->helpTopic, sizeof(ctx->helpTopic), "settings.video");When the user presses F1, the shell launches the help viewer with your help file opened to the specified topic.
-Launching Help from Menus
+Launching Help from Menus
To add a Help menu item that opens your help file:
shellLoadAppWithArgs(ctx, viewerPath, helpFilePath);Welcome!
-Welcome!
-
DVX (DOS Visual eXecutive) is a graphical user interface environment for DOS, designed for 486-class hardware and above. This help file covers the system architecture, core API, libraries, and widget toolkit.
DVX Architecture Overview
-DVX Architecture Overview
DOS Visual eXecutive -- A Windowing GUI for DJGPP/DPMI
DVX (DOS Visual eXecutive) is a complete windowing GUI compositor targeting DJGPP/DPMI on DOS. It provides overlapping windows with Motif-style chrome, a retained-mode widget toolkit, cooperative multitasking of DXE-loaded applications, and a dirty-rectangle compositor optimized for 486/Pentium hardware.
-Key Design Constraints
+Key Design Constraints
- VESA VBE 2.0+ LFB only -- no bank switching. If the hardware cannot provide a linear framebuffer, initialization fails.
- 486 baseline -- all hot paths are written to be fast on a 486, with Pentium-specific paths where the gain is significant. @@ -781,7 +779,7 @@ img { max-width: 100%; }
No external font or cursor files -- all bitmaps are compiled in as static const data.
The runtime environment consists of a bootstrap loader (dvx.exe) that loads core DXE libraries, widget plugins, and the shell, which in turn loads and manages DXE application modules.
-Contents
+Contents
@@ -795,7 +793,6 @@ img { max-width: 100%; }Five-Layer Architecture
-Five-Layer Architecture
DVX is organized into five layers, each implemented as a single .h/.c pair. Every header includes dvxTypes.h (the shared type definitions) to avoid circular dependencies. The layers are strictly stacked: each layer depends only on the layers below it.
Applications (DXE .app modules)
==================================================
@@ -827,7 +824,7 @@ img { max-width: 100%; }
| | DisplayT, WindowT, RectT, ColorSchemeT | |
| +------------------------------------------+ |
==================================================Layer Summary
+Layer Summary
Layer Header Responsibility
----- ------ --------------
1 - Video dvxVideo.h VESA VBE mode negotiation, LFB mapping via DPMI, backbuffer allocation, packColor() (RGB to native pixel format), display-wide clip rectangle.
@@ -838,10 +835,9 @@ img { max-width: 100%; }
Display Pipeline
-Display Pipeline
The double-buffer strategy is the single most important performance decision in DVX. All drawing goes to a system RAM backbuffer (DisplayT.backBuf); only dirty rectangles are flushed to the linear framebuffer (DisplayT.lfb) in video memory.
This matters because writes to video memory over the PCI bus are 10-50x slower than writes to main RAM on 486/Pentium hardware for random-access patterns.
-Per-Frame Compositing Pipeline
+Per-Frame Compositing Pipeline
1. Input poll (mouse, keyboard)
|
2. Event dispatch (focus window callbacks)
@@ -863,11 +859,11 @@ img { max-width: 100%; }
6. flushRect() -- copy each dirty rect from backBuf to LFB
|
7. Yield (platformYield)Key Data Structures
+Key Data Structures
DisplayT -- Central display context: width, height, pitch, pixel format, LFB pointer, backbuffer pointer, palette, clip rectangle. Passed by pointer through every layer -- no globals.
BlitOpsT -- Vtable of span fill/copy function pointers resolved at init time for the active pixel depth. On DOS these dispatch to hand-written rep stosl / rep movsd asm inner loops.
DirtyListT -- Fixed-capacity dynamic array of RectT. Linear scanning for merge candidates is cache-friendly at typical sizes (under 128 rects). If the list fills up, the compositor merges aggressively or falls back to full-screen repaint.
-Why This Works on a 486
+Why This Works on a 486
- A full 640x480x32bpp frame is 1.2 MB -- far too much to flush every frame over a slow PCI bus.
- A typical dirty region during normal interaction (typing, menu open) is a few KB. @@ -877,8 +873,7 @@ img { max-width: 100%; }
Window System
-Window System
-WindowT Structure
+WindowT Structure
Each WindowT is the central object of the window manager. Key fields:
Field Group Purpose
----------- -------
@@ -888,7 +883,7 @@ img { max-width: 100%; }
Chrome state (menuBar, vScroll, hScroll) Optional menu bar and scrollbars. Affect content area computation.
Widget tree (widgetRoot) Root of the retained-mode widget tree (NULL if using raw callbacks).
Callbacks onPaint, onKey, onKeyUp, onMouse, onResize, onClose, onMenu, onScroll, onFocus, onBlur, onCursorQuery.
-Window Stack (Z-Order)
+Window Stack (Z-Order)
WindowStackT is an array of WindowT* ordered front-to-back: index count-1 is the topmost window. This allows:
- Back-to-front iteration for painting (painter's algorithm). @@ -896,7 +891,7 @@ img { max-width: 100%; }
Reordering by pointer swap (no copying of large WindowT structs).
Only one drag/resize/scroll operation can be active system-wide at a time (single mouse), so that state lives on the stack, not on individual windows.
-Chrome Layout
+Chrome Layout
+-------------------------------------------+
| 4px outer border (raised bevel) |
| +-------------------------------------+ |
@@ -923,31 +918,30 @@ img { max-width: 100%; }
CHROME_MENU_HEIGHT = 20px
SCROLLBAR_WIDTH = 16px
CHROME_CLOSE_BTN_SIZE = 16pxHit Test Regions
+Hit Test Regions
wmHitTest() iterates the stack front-to-back and returns a hit-part identifier: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, HIT_RESIZE, HIT_MENU, HIT_VSCROLL, HIT_HSCROLL, HIT_MINIMIZE, HIT_MAXIMIZE. Resize edge detection returns a bitmask of RESIZE_LEFT, RESIZE_RIGHT, RESIZE_TOP, RESIZE_BOTTOM (corners combine two edges).
-Menu System
+Menu System
Menus use fixed-size arrays with inline char buffers (no heap strings). Up to 8 menus per bar, items dynamically allocated. Supports cascading submenus via MenuItemT.subMenu pointer. Item types: normal, checkbox, radio. Separators are non-interactive items. The popup state (PopupStateT) tracks a stack of parent frames for cascading submenu nesting.
-Minimized Windows
+Minimized Windows
Minimized windows display as 64x64 icons at the bottom of the screen with beveled borders, similar to a classic desktop icon bar. Icons show a scaled-down preview of the window's content buffer, refreshed one per frame in a round-robin fashion to amortize the scaling cost.
Widget System
-Widget System
The widget system (dvxWidget.h) is a retained-mode toolkit layered on top of the window manager. Widgets form a tree rooted at a per-window VBox container.
-WidgetT Base Structure
+WidgetT Base Structure
Every widget shares the same WidgetT struct. The type field is a runtime-assigned integer ID. The wclass pointer references the widget's WidgetClassT vtable. Widget-specific private data is stored in w->data (opaque void*).
Tree linkage: parent, firstChild, lastChild, nextSibling. No prevSibling -- this halves pointer overhead and removal is still O(n) for typical tree depths of 5-10.
-Layout Engine
+Layout Engine
Two-pass flexbox-like algorithm:
- Bottom-up (calcMinSize) -- compute minimum sizes for every widget, starting from leaves.
Top-down (layout) -- allocate space within available bounds, distributing extra space according to weight values (0 = fixed, 100 = normal stretch).
Size hints use a tagged encoding: the top 2 bits of an int32_t select the unit (pixels, character widths, or percentage of parent), the low 30 bits hold the value. Macros: wgtPixels(v), wgtChars(v), wgtPercent(v).
-Widget Class Dispatch (WidgetClassT)
+Widget Class Dispatch (WidgetClassT)
Each widget type provides a WidgetClassT with a handlers[] array indexed by stable method IDs. Method IDs are never reordered or reused -- new methods append at the end. This provides ABI-stable dispatch so that widget DXEs compiled against an older DVX version continue to work.
Methods include: PAINT, PAINT_OVERLAY, CALC_MIN_SIZE, LAYOUT, ON_MOUSE, ON_KEY, ON_ACCEL_ACTIVATE, DESTROY, GET_TEXT, SET_TEXT, POLL, and more (21 defined, room for 32).
-Class Flags
+Class Flags
Flag Meaning
---- -------
WCLASS_FOCUSABLE Can receive keyboard focus (Tab navigation)
@@ -958,7 +952,7 @@ img { max-width: 100%; }
WCLASS_NEEDS_POLL Needs periodic polling (e.g. AnsiTerm comms)
WCLASS_SWALLOWS_TAB Tab key goes to widget, not focus navigation
WCLASS_PRESS_RELEASE Click = press + release (buttons)
-Available Widget Types
+Available Widget Types
Each widget is a separate .wgt DXE module. 29 widget types are included:
Widget Description
------ -----------
@@ -991,22 +985,21 @@ img { max-width: 100%; }
Toolbar Toolbar with icon buttons
TreeView Hierarchical tree display
WrapBox Flow layout (wrapping horizontal container)
-Widget API Registry
+Widget API Registry
Each widget DXE registers a small API struct under a name during wgtRegister(). Callers retrieve it via wgtGetApi("button") and cast to the widget-specific API type. Per-widget headers provide typed accessors so callers avoid manual casts. Adding a new widget requires zero changes to the core.
-Widget Interface Descriptors (WgtIfaceT)
+Widget Interface Descriptors (WgtIfaceT)
Each widget can register an interface descriptor that describes its BASIC-facing properties, methods, and events. These descriptors are used by the form runtime and IDE for generic dispatch and property panel enumeration. Properties have typed getters/setters (WGT_IFACE_STRING, WGT_IFACE_INT, WGT_IFACE_BOOL, WGT_IFACE_ENUM).
DXE Module System
-DXE Module System
DVX uses DJGPP's DXE3 (Dynamic eXtension) format for all loadable modules. DXE3 supports RTLD_GLOBAL symbol sharing -- symbols exported by one module are visible to all subsequently loaded modules. This is critical: widget DXEs call core API functions (e.g. rectFill, wgtInvalidate) that are exported by the core library DXE.
-Module Types
+Module Types
Extension Directory Purpose Examples --------- --------- ------- -------- .lib LIBS/ Core libraries loaded first. Provide infrastructure APIs. libtasks.lib, libdvx.lib, dvxshell.lib .wgt WIDGETS/ Widget type plugins. Each exports wgtRegister(). button.wgt, listview.wgt, terminal.wgt .app APPS/*/ Application modules. Each exports appDescriptor and appMain(). Loaded on demand by the shell. progman.app, notepad.app, cpanel.app-
Boot Sequence
+Boot Sequence
dvx.exe (loader)
|
+-- Enter VGA mode 13h, display splash screen with progress bar
@@ -1027,20 +1020,19 @@ img { max-width: 100%; }
|
+-- Main loop:
dvxUpdate() -> tsYield() -> shellReapApps()Application Lifecycle
+Application Lifecycle
Two kinds of DXE apps:
-Callback-only (hasMainLoop = false)
+Callback-only (hasMainLoop = false)
appMain() creates windows, registers callbacks, and returns. The app lives through GUI callbacks driven by the shell's main loop. Lifecycle ends when the last window is closed. No extra task stack needed -- simpler and cheaper.
-Main-loop (hasMainLoop = true)
+Main-loop (hasMainLoop = true)
A dedicated cooperative task is created. appMain() runs in that task with its own loop, calling tsYield() to share CPU. Needed for apps with continuous work (terminal emulators, games). Lifecycle ends when appMain() returns.
-Crash Recovery
+Crash Recovery
The platform layer installs signal handlers for SIGSEGV, SIGFPE, SIGILL. On crash, the handler logs platform-specific diagnostics (register dump on DJGPP), then longjmps back to the shell's main loop. The crashed app is killed; other apps and the shell survive. This provides Windows 3.1-style fault tolerance.
-Per-App Memory Tracking
+Per-App Memory Tracking
All allocations route through dvxMalloc/dvxFree wrappers that prepend a 16-byte header recording the owning app ID and allocation size. The Task Manager displays per-app memory usage, and leaks are detected at app termination.
Event Model
-Event Model
DVX uses a cooperative polling model. The main loop (dvxRun / dvxUpdate) runs this cycle each frame:
- Poll mouse -- platformMousePoll() returns position and button bitmask. Compare with previous frame for press/release edge detection. @@ -1049,7 +1041,7 @@ img { max-width: 100%; }
- Compositor pass -- merge dirty rects, composite, flush to LFB.
Yield -- platformYield() or idle callback.
-Event Dispatch Chain
+Event Dispatch Chain
Mouse/Keyboard Input
|
Global handlers (Ctrl+Esc, modal filter)
@@ -1067,18 +1059,17 @@ img { max-width: 100%; }
wclsOnMouse / wclsOnKey (vtable dispatch)
|
Universal callbacks (onClick, onChange, etc.)Accelerator Tables
+Accelerator Tables
Per-window accelerator tables map key + modifier combinations to command IDs. The runtime normalizes key/modifier at registration time (uppercase key, strip shift from modifiers) so matching at dispatch time is two integer comparisons per entry. Matched accelerators fire the window's onMenu callback with the command ID, unifying the menu and hotkey code paths.
-Mouse Cursor
+Mouse Cursor
Software-rendered cursor using the classic AND/XOR mask approach. Seven cursor shapes are compiled in: arrow, horizontal resize, vertical resize, NW-SE diagonal resize, NE-SW diagonal resize, busy (hourglass), and crosshair. The cursor is painted into the backbuffer on top of the composited frame and the affected region is flushed to the LFB each frame.
-Double-Click Detection
+Double-Click Detection
Timestamp-based: two clicks on the same target (title bar, minimized icon, close gadget) within the configurable double-click interval trigger the double-click action. Separate tracking for each target type.
Font System
-Font System
DVX uses fixed-width 8-pixel-wide bitmap fonts only. One size is provided: 8x16, matching the standard VGA ROM font and CP437 encoding (256 glyphs).
-BitmapFontT
+BitmapFontT
typedef struct {
int32_t charWidth; // fixed width per glyph (always 8)
int32_t charHeight; // 16
@@ -1094,18 +1085,17 @@ img { max-width: 100%; }
No glyph-width tables, kerning, or per-character positioning needed.
8-pixel width aligns with byte boundaries -- no bit shifting in per-scanline rendering.
-Text Rendering Functions
+Text Rendering Functions
drawChar() -- Renders a single character. Supports opaque (background fill) and transparent modes.
drawTextN() -- Optimized batch rendering for a known character count. Clips once for the entire run, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character rendering for long runs.
drawTermRow() -- Renders an 80-column terminal row in a single pass, with per-cell foreground/background from a 16-color palette, blink attribute support, and cursor rendering. Exists because per-character terminal rendering is unacceptably slow on target hardware.
drawTextAccel() -- Renders text with & accelerator markers. The character after & is underlined to indicate the keyboard shortcut.
-Performance Optimization
+Performance Optimization
AppContextT stores a fixed-point 16.16 reciprocal of font.charHeight (charHeightRecip) so that dividing by charHeight (for pixel-to-row conversion in terminal/text widgets) becomes a multiply+shift instead of an integer divide, which costs 40+ cycles on a 486.
Color System
-Color System
-Pixel Format
+Pixel Format
PixelFormatT describes the active VESA mode's pixel encoding. Populated once from the VBE mode info block. Stores shift, mask, and bit count for each channel so packColor() can convert RGB to native format with shift-and-mask arithmetic -- no per-pixel computation.
Supported depths:
Depth Bytes/Pixel Notes
@@ -1114,7 +1104,7 @@ img { max-width: 100%; }
15 bpp 2 5-5-5 RGB (1 bit unused).
16 bpp 2 5-6-5 RGB.
32 bpp 4 8-8-8 RGB (8 bits unused).
-ColorSchemeT -- Theming
+ColorSchemeT -- Theming
All 20 UI colors are pre-packed into display pixel format at init time. Every color is a uint32_t that can be written directly to the framebuffer with zero per-pixel conversion. The scheme must be regenerated on video mode change, but mode changes require re-init anyway.
Color roles mirror classic Motif/Windows 3.x conventions:
-
@@ -1128,7 +1118,7 @@ img { max-width: 100%; }
cursorFg/Bg -- mouse cursor colors
Source RGB values are kept in AppContextT.colorRgb[] for theme save/load. Themes are stored as INI files with a [colors] section. The API provides dvxLoadTheme(), dvxSaveTheme(), dvxSetColor(), and dvxResetColorScheme().
-Bevel Styles
+Bevel Styles
Bevels are the defining visual element of the Motif aesthetic. Convenience macros create bevel style descriptors by swapping highlight and shadow colors:
BEVEL_RAISED(colorScheme, borderWidth) -- raised 3D look
BEVEL_SUNKEN(colorScheme, face, borderWidth) -- sunken/inset look
@@ -1137,36 +1127,34 @@ img { max-width: 100%; }
Platform Layer
-Platform Layer
All OS-specific and CPU-specific code is isolated behind dvxPlatform.h. To port DVX, implement a new dvxPlatformXxx.c against this header.
-Implementations
+Implementations
File Target Details ---- ------ ------- dvxPlatformDos.c DJGPP/DPMI Real VESA VBE, INT 33h mouse, INT 16h keyboard, rep movsd/rep stosl asm spans, DPMI physical memory mapping for LFB, INT 9 hook for key-up, CuteMouse Wheel API.-
Abstraction Areas
-Video
+Abstraction Areas
+Video
platformVideoInit() -- mode probe and framebuffer setup. platformVideoShutdown() -- restore previous mode. platformVideoEnumModes() -- enumerate available modes.
-Framebuffer Flush
+Framebuffer Flush
platformFlushRect() -- copy dirty rect from backBuf to LFB. On DOS, each scanline uses rep movsd for near-optimal aligned 32-bit writes over the PCI bus.
-Optimized Memory Spans
+Optimized Memory Spans
Six functions: platformSpanFill8/16/32() and platformSpanCopy8/16/32(). Called once per scanline of every rectangle fill, blit, and text draw. On DOS these use inline assembly for critical inner loops.
-Mouse Input
+Mouse Input
Polling model. platformMousePoll() returns position and button bitmask. Wheel support via CuteMouse API.
-Keyboard Input
+Keyboard Input
platformKeyboardRead() -- non-blocking key read. platformKeyUpRead() -- key release detection (requires INT 9 hook on DOS). platformAltScanToChar() -- scancode-to-ASCII lookup for Alt+key combinations.
-Crash Recovery
+Crash Recovery
platformInstallCrashHandler() -- signal handlers + longjmp for fault tolerance.
-DXE Support
+DXE Support
platformRegisterDxeExports() -- register C runtime and platform symbols for DXE resolution. platformRegisterSymOverrides() -- register function pointer overrides for module loader.
Build System
-Build System
-Cross-Compilation
+Cross-Compilation
DVX is cross-compiled from Linux using a DJGPP cross-compiler (i586-pc-msdosdjgpp-gcc). The top-level Makefile orchestrates building all subsystems in dependency order.
make -- build everything
./mkcd.sh -- build + create ISO for 86BoxBuild Targets
+Build Targets
all: core tasks loader texthelp listhelp tools widgets shell taskmgr serial sql apps Target Output Description
------ ------ -----------
@@ -1182,7 +1170,7 @@ img { max-width: 100%; }
tools bin/dvxres Resource compiler (runs on Linux, builds resource sections into DXEs)
serial serial DXE libs UART driver, HDLC packets, security, seclink
sql SQL DXE lib SQLite integration
-DXE3 Build Process
+DXE3 Build Process
Each DXE module is compiled to an object file with GCC, then linked with dxe3gen:
# Compile
i586-pc-msdosdjgpp-gcc -O2 -march=i486 -mtune=i586 -c -o widget.o widget.c
@@ -1193,7 +1181,7 @@ img { max-width: 100%; }
# Optionally append resources
dvxres build widget.wgt widget.resThe -E flag specifies exported symbols (prefixed with underscore per DJGPP convention). -U marks unresolved symbols as OK (they'll be resolved at load time from previously loaded DXEs).
-Deployment (mkcd.sh)
+Deployment (mkcd.sh)
- Runs make all.
- Verifies critical outputs exist (dvx.exe, libtasks.lib, libdvx.lib, dvxshell.lib). @@ -1201,12 +1189,12 @@ img { max-width: 100%; }
- Creates an ISO 9660 image from bin/ using mkisofs: -iso-level 1 (strict 8.3 filenames for DOS), -J (Joliet extensions for long names), -V DVX (volume label).
Places the ISO at ~/.var/app/net._86box._86Box/data/86Box/dvx.iso for 86Box to mount as CD-ROM.
-Compiler Flags
+Compiler Flags
-O2 Optimization level 2
-march=i486 486 instruction set baseline
-mtune=i586 Optimize scheduling for Pentium
-Wall -Wextra Full warningsDirectory Layout
+Directory Layout
dvxgui/
+-- core/ Core library sources (dvxVideo, dvxDraw, dvxComp, dvxWm, dvxApp, widget infra)
| +-- platform/ Platform abstraction (dvxPlatform.h, dvxPlatformDos.c)
@@ -1244,10 +1232,9 @@ img { max-width: 100%; }
DVX GUI API Reference
-DVX GUI API Reference
DOS Visual eXecutive -- Complete public API documentation generated from source headers.
The DVX GUI is built as a five-layer architecture. Each layer is defined in its own header file. This reference covers every public function, type, and constant.
-Layers
+Layers
- dvxTypes.h -- Shared type definitions
- dvxCursor.h -- Cursor definitions @@ -1269,10 +1256,9 @@ img { max-width: 100%; }
dvxTypes.h -- Shared Type Definitions
-dvxTypes.h -- Shared Type Definitions
Central type definitions shared across all five layers of the DVX GUI stack. Every header includes this file. Contains no function definitions -- only structs, enums, typedefs, and compile-time constants.
-Core Structures
-PixelFormatT
+Core Structures
+PixelFormatT
Describes the pixel encoding for the active VESA video mode. Populated once at startup from the VBE mode info block, then treated as read-only.
Field Description
----- -----------
@@ -1281,7 +1267,7 @@ img { max-width: 100%; }
uint32_t redMask, greenMask, blueMask Bitmasks for each color channel
int32_t redShift, greenShift, blueShift Bit position of each color field
int32_t redBits, greenBits, blueBits Number of bits per channel
-DisplayT
+DisplayT
Single display context passed by pointer through every layer. All drawing targets the backBuf; only dirty rects are flushed to lfb.
Field Description
----- -----------
@@ -1292,13 +1278,13 @@ img { max-width: 100%; }
uint8_t *backBuf System RAM backbuffer
uint8_t *palette 768 bytes for 8-bit mode, NULL otherwise
int32_t clipX, clipY, clipW, clipH Current clip rectangle
-RectT
+RectT
Rectangle in origin + extent form. Used throughout the compositor, window manager, and widget layout engine.
Field Description ----- ----------- int32_t x, y Top-left corner int32_t w, h Width and height-
BlitOpsT
+BlitOpsT
Vtable for hot-path span operations. Resolved at init time based on pixel depth. On DOS, these dispatch to hand-written asm (rep stosl / rep movsd).
Field Description
----- -----------
@@ -1306,7 +1292,7 @@ img { max-width: 100%; }
SpanCopyFnT spanCopy Copy a horizontal span between buffers
int32_t bytesPerPixel Bytes per pixel for the active mode
int32_t pitch Bytes per scanline
-BevelStyleT
+BevelStyleT
Bevel drawing parameters. Swapping highlight/shadow flips raised vs. sunken appearance.
Field Description
----- -----------
@@ -1314,7 +1300,7 @@ img { max-width: 100%; }
uint32_t shadow Darker color (bottom/right edges)
uint32_t face Interior fill color (0 = no fill)
int32_t width Border thickness in pixels (typically 2)
-BitmapFontT
+BitmapFontT
Fixed-width 8-pixel-wide bitmap font descriptor. One size provided: 8x16 (standard VGA ROM font, CP437 encoding).
Field Description
----- -----------
@@ -1323,7 +1309,7 @@ img { max-width: 100%; }
int32_t firstChar ASCII code of first glyph (typically 0)
int32_t numChars Number of glyphs (typically 256)
const uint8_t *glyphData Packed 1bpp data, charHeight bytes per glyph
-ColorSchemeT
+ColorSchemeT
All UI colors pre-packed into display pixel format at init time. Theme support is achieved by swapping this struct.
Field Description
----- -----------
@@ -1339,17 +1325,17 @@ img { max-width: 100%; }
uint32_t buttonFace Button face color
uint32_t scrollbarBg, scrollbarFg, scrollbarTrough Scrollbar element colors
uint32_t cursorFg, cursorBg Mouse cursor colors
-ColorIdE
+ColorIdE
Enum for addressing individual colors in ColorSchemeT. Order matches struct field order.
Values: ColorDesktopE, ColorWindowFaceE, ColorWindowHighlightE, ColorWindowShadowE, ColorActiveTitleBgE, ColorActiveTitleFgE, ColorInactiveTitleBgE, ColorInactiveTitleFgE, ColorContentBgE, ColorContentFgE, ColorMenuBgE, ColorMenuFgE, ColorMenuHighlightBgE, ColorMenuHighlightFgE, ColorButtonFaceE, ColorScrollbarBgE, ColorScrollbarFgE, ColorScrollbarTroughE, ColorCursorFgE, ColorCursorBgE, ColorCountE.
-DirtyListT
+DirtyListT
Fixed-capacity list of dirty rectangles. Dynamic array, grows on demand.
Field Description ----- ----------- RectT *rects Dynamic array of dirty rectangles int32_t count Current number of dirty rects int32_t cap Allocated capacity-
WindowT
+WindowT
Central window object. Each window owns a persistent content backbuffer and receives events through callback function pointers.
Field Description
----- -----------
@@ -1387,7 +1373,7 @@ img { max-width: 100%; }
onCursorQuery(WindowT *win, int32_t x, int32_t y) Return CURSOR_* for hit position
onFocus(WindowT *win) Window gained focus
onBlur(WindowT *win) Window lost focus
-WindowStackT
+WindowStackT
Z-ordered window stack (front-to-back: index count-1 is topmost). Owns system-wide drag/resize/scroll interaction state.
Field Description
----- -----------
@@ -1397,7 +1383,7 @@ img { max-width: 100%; }
int32_t dragWindow, dragOffX, dragOffY Active drag state
int32_t resizeWindow, resizeEdge Active resize state
int32_t scrollWindow, scrollOrient, scrollDragOff Active scroll drag state
-MenuT / MenuItemT / MenuBarT
+MenuT / MenuItemT / MenuBarT
Menu system types. Fixed-size label buffers (MAX_MENU_LABEL = 32). Cascading submenus supported via MenuItemT.subMenu pointer.
Field Description
----- -----------
@@ -1408,7 +1394,7 @@ img { max-width: 100%; }
MenuItemT.enabled, checked Item state
MenuItemT.subMenu Child menu for cascading (NULL if leaf)
MenuBarT.activeIdx Open popup index (-1 = none)
-ScrollbarT
+ScrollbarT
Window-level scrollbar state. Managed by the WM layer, drawn after content.
Field Description
----- -----------
@@ -1417,20 +1403,20 @@ img { max-width: 100%; }
int32_t value Current position
int32_t pageSize Visible portion (for proportional thumb sizing)
int32_t x, y, length Computed screen position and track length
-AccelTableT / AccelEntryT
+AccelTableT / AccelEntryT
Per-window keyboard accelerator table. Entries are matched against keystrokes in the event loop and fire onMenu(cmdId) on match.
Field Description ----- ----------- AccelEntryT.key ASCII character or KEY_Fxx constant AccelEntryT.modifiers Bitmask of ACCEL_CTRL, ACCEL_SHIFT, ACCEL_ALT AccelEntryT.cmdId Command ID passed to onMenu-
VideoModeInfoT
+VideoModeInfoT
Describes an available video mode (enumerated at init).
Field Description ----- ----------- int32_t w, h Resolution int32_t bpp Bits per pixel-
CursorT
+CursorT
Software-rendered 16x16 cursor using AND/XOR mask encoding.
Field Description
----- -----------
@@ -1438,14 +1424,14 @@ img { max-width: 100%; }
int32_t hotX, hotY Hot spot coordinates
const uint16_t *andMask AND mask (0 = draw pixel, 1 = transparent)
const uint16_t *xorData XOR data (0 = black, 1 = white where AND = 0)
-Bevel Convenience Macros
+Bevel Convenience Macros
Macro Description ----- ----------- BEVEL_RAISED(cs, bw) Raised bevel style from ColorSchemeT ptr and border width BEVEL_SUNKEN(cs, face, bw) Sunken bevel style with explicit face color BEVEL_TROUGH(cs) 1px sunken trough (for scrollbar tracks) BEVEL_SB_BUTTON(cs) 1px raised scrollbar button-
Chrome Constants
+Chrome Constants
Define Value Description
------ ----- -----------
CHROME_BORDER_WIDTH 4 Outer frame border width
@@ -1457,7 +1443,7 @@ img { max-width: 100%; }
CHROME_TOTAL_SIDE 6 Total inset from side of frame to content
CHROME_TOTAL_BOTTOM 6 Total inset from bottom of frame to content
CHROME_CLOSE_BTN_SIZE 16 Close button gadget size
-Hit Test Constants
+Hit Test Constants
Define Value Description
------ ----- -----------
HIT_CONTENT 0 Content area
@@ -1470,19 +1456,19 @@ img { max-width: 100%; }
HIT_MINIMIZE 7 Minimize gadget
HIT_MAXIMIZE 8 Maximize gadget
HIT_NONE -1 No window hit (desktop)
-Mouse Button Flags
+Mouse Button Flags
Define Value Description ------ ----- ----------- MOUSE_LEFT 1 Left mouse button MOUSE_RIGHT 2 Right mouse button MOUSE_MIDDLE 4 Middle mouse button-
Accelerator Modifier Flags
+Accelerator Modifier Flags
Define Value Description ------ ----- ----------- ACCEL_SHIFT 0x03 Shift key (matches BIOS shift state bits) ACCEL_CTRL 0x04 Ctrl key ACCEL_ALT 0x08 Alt key-
Extended Key Codes
+Extended Key Codes
Define Description
------ -----------
KEY_F1 .. KEY_F12 Function keys (scancode | 0x100)
@@ -1492,7 +1478,7 @@ img { max-width: 100%; }
KEY_END End key
KEY_PGUP Page Up key
KEY_PGDN Page Down key
-Resize Edge Flags
+Resize Edge Flags
Define Value Description
------ ----- -----------
RESIZE_NONE 0 No resize edge
@@ -1500,7 +1486,7 @@ img { max-width: 100%; }
RESIZE_RIGHT 2 Right edge
RESIZE_TOP 4 Top edge
RESIZE_BOTTOM 8 Bottom edge (combinable via OR for corners)
-Utility Macros
+Utility Macros
Macro Description
----- -----------
DVX_MIN(a, b) Return the smaller of two values
@@ -1508,9 +1494,8 @@ img { max-width: 100%; }
dvxCursor.h -- Cursor Definitions
-dvxCursor.h -- Cursor Definitions
Embedded 16x16 mouse cursor bitmaps compiled as static const data. No external cursor files. Uses the standard AND/XOR mask encoding from the IBM VGA hardware cursor spec.
-Cursor Shape IDs
+Cursor Shape IDs
Define Value Description
------ ----- -----------
CURSOR_ARROW 0 Standard arrow (hot spot at tip)
@@ -1521,15 +1506,14 @@ img { max-width: 100%; }
CURSOR_BUSY 5 Hourglass (wait)
CURSOR_CROSSHAIR 6 Crosshair for placement
CURSOR_COUNT 7 Total number of cursor shapes
-Data
-dvxCursors[CURSOR_COUNT]
+Data
+dvxCursors[CURSOR_COUNT]
Static const array of CursorT structs, indexed by CURSOR_xxx constants. Each entry includes the AND mask, XOR data, dimensions, and hot spot coordinates.
dvxVideo.h -- Layer 1: VESA VBE Video Backend
-dvxVideo.h -- Layer 1: VESA VBE Video Backend
The lowest layer. Responsible for VESA VBE mode negotiation, LFB mapping via DPMI, system RAM backbuffer allocation, pixel format discovery, and color packing. LFB-only design: bank switching is deliberately unsupported.
-videoInit
+videoInit
int32_t videoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);Probe VBE for a mode matching the requested resolution and depth, enable it, map the LFB into DPMI linear address space, and allocate a system RAM backbuffer. preferredBpp is a hint; the closest available depth is used if an exact match is not found.
Parameter Description
@@ -1538,13 +1522,13 @@ img { max-width: 100%; }
requestedW/H Desired screen resolution
preferredBpp Preferred bits per pixel (8, 15, 16, or 32)
Returns: 0 on success, negative on failure.
-videoShutdown
+videoShutdown
void videoShutdown(DisplayT *d);Restore VGA text mode (mode 3), unmap the LFB, and free the backbuffer. Safe to call even if videoInit() failed.
Parameter Description --------- ----------- d Display context to shut down-
packColor
+packColor
uint32_t packColor(const DisplayT *d, uint8_t r, uint8_t g, uint8_t b);Pack an RGB triplet into the display's native pixel format. For direct-color modes (15/16/32 bpp), returns a packed pixel value using shift/mask fields. For 8-bit mode, returns the nearest palette index via Euclidean distance in RGB space.
Parameter Description
@@ -1552,14 +1536,14 @@ img { max-width: 100%; }
d Display context (provides pixel format)
r, g, b Color components (0-255)
Returns: Native pixel value suitable for direct framebuffer write.
-setClipRect
+setClipRect
void setClipRect(DisplayT *d, int32_t x, int32_t y, int32_t w, int32_t h);Set the clip rectangle on the display. All subsequent draw operations clip to this rectangle. The caller must save and restore the clip rect around scoped operations.
Parameter Description --------- ----------- d Display context x, y, w, h Clip rectangle in screen coordinates-
resetClipRect
+resetClipRect
void resetClipRect(DisplayT *d);Reset the clip rectangle to the full display dimensions.
Parameter Description
@@ -1568,16 +1552,15 @@ img { max-width: 100%; }
dvxDraw.h -- Layer 2: Drawing Primitives
-dvxDraw.h -- Layer 2: Drawing Primitives
All 2D drawing operations: rectangle fills, bitmap blits, text rendering, bevels, lines, and cursor rendering. Every function draws into the display's backbuffer and clips to the current clip rectangle. This layer is stateless beyond the clip rect on DisplayT.
-drawInit
+drawInit
void drawInit(BlitOpsT *ops, const DisplayT *d);Populate a BlitOpsT with the correct span functions for the display's pixel depth. Must be called once after videoInit().
Parameter Description --------- ----------- ops BlitOpsT to populate d Initialized display context-
rectFill
+rectFill
void rectFill(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);Fill a rectangle with a solid color. Clips to the display clip rect. Workhorse for backgrounds, window fills, and clear operations.
Parameter Description
@@ -1586,7 +1569,7 @@ img { max-width: 100%; }
ops Blit operations vtable
x, y, w, h Rectangle to fill
color Packed pixel color
-rectCopy
+rectCopy
void rectCopy(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);Copy a rectangle from an arbitrary source buffer into the backbuffer. Used to blit per-window content buffers during compositing.
Parameter Description
@@ -1598,7 +1581,7 @@ img { max-width: 100%; }
srcPitch Source buffer bytes per row
srcX, srcY Origin within source buffer
w, h Rectangle dimensions to copy
-rectCopyGrayscale
+rectCopyGrayscale
void rectCopyGrayscale(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);Copy a rectangle with grayscale conversion. Each pixel's RGB is converted to luminance (0.299R + 0.587G + 0.114B) for a disabled/grayed appearance.
Parameter Description
@@ -1609,7 +1592,7 @@ img { max-width: 100%; }
srcBuf, srcPitch Source buffer and pitch
srcX, srcY Source origin
w, h Rectangle dimensions
-drawBevel
+drawBevel
void drawBevel(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const BevelStyleT *style);Draw a beveled frame. Top/left edges in highlight color, bottom/right in shadow. Interior filled with face color if non-zero.
Parameter Description
@@ -1618,7 +1601,7 @@ img { max-width: 100%; }
ops Blit operations vtable
x, y, w, h Outer bevel rectangle
style Bevel colors and width
-drawChar
+drawChar
int32_t drawChar(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, char ch, uint32_t fg, uint32_t bg, bool opaque);Draw a single character glyph. When opaque is true, the background fills the entire cell; when false, only foreground pixels are drawn (transparent background).
Parameter Description
@@ -1631,7 +1614,7 @@ img { max-width: 100%; }
fg, bg Foreground and background packed colors
opaque true = fill background, false = transparent
Returns: Advance width (always charWidth).
-drawText
+drawText
void drawText(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);Draw a null-terminated string. Calls drawChar per character.
Parameter Description
@@ -1643,7 +1626,7 @@ img { max-width: 100%; }
text Null-terminated string
fg, bg Foreground and background packed colors
opaque true = fill background, false = transparent
-drawTextN
+drawTextN
void drawTextN(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, int32_t count, uint32_t fg, uint32_t bg, bool opaque);Optimized batch text rendering for a known character count. Computes clip bounds once, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character drawChar for long runs (terminal rows, list items).
Parameter Description
@@ -1656,7 +1639,7 @@ img { max-width: 100%; }
count Number of characters to render
fg, bg Foreground and background packed colors
opaque true = fill background, false = transparent
-textWidth
+textWidth
int32_t textWidth(const BitmapFontT *font, const char *text);Return the pixel width of a null-terminated string (strlen(text) * charWidth).
Parameter Description
@@ -1664,14 +1647,14 @@ img { max-width: 100%; }
font Bitmap font
text Null-terminated string
Returns: Width in pixels.
-accelParse
+accelParse
char accelParse(const char *text);Scan text for an & prefix and return the following character as a lowercase accelerator key. "&File" returns 'f', "E&xit" returns 'x'.
Parameter Description --------- ----------- text Text with optional & accelerator marker
Returns: Lowercase accelerator character, or 0 if none.
-drawTextAccel
+drawTextAccel
void drawTextAccel(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);Draw text with & accelerator markers. The character after & is drawn underlined to indicate the keyboard shortcut. && produces a literal &. Used for menu items and button labels.
Parameter Description
@@ -1683,7 +1666,7 @@ img { max-width: 100%; }
text Text with & markers
fg, bg Foreground and background packed colors
opaque true = fill background, false = transparent
-textWidthAccel
+textWidthAccel
int32_t textWidthAccel(const BitmapFontT *font, const char *text);Measure text width excluding & markers (so "&File" measures as 4 chars).
Parameter Description
@@ -1691,7 +1674,7 @@ img { max-width: 100%; }
font Bitmap font
text Text with optional & markers
Returns: Width in pixels.
-drawMaskedBitmap
+drawMaskedBitmap
void drawMaskedBitmap(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const uint16_t *andMask, const uint16_t *xorData, uint32_t fgColor, uint32_t bgColor);Draw a 1-bit AND/XOR masked bitmap. Used for software-rendered mouse cursors.
Parameter Description
@@ -1703,7 +1686,7 @@ img { max-width: 100%; }
andMask AND transparency mask (one uint16_t per row)
xorData XOR color data
fgColor, bgColor Cursor foreground and background packed colors
-drawTermRow
+drawTermRow
void drawTermRow(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, int32_t cols, const uint8_t *lineData, const uint32_t *palette, bool blinkVisible, int32_t cursorCol);Render an entire row of terminal character cells (ch/attr byte pairs) in a single pass. Colors looked up from a 16-color palette. Attribute bit 7 controls blink.
Parameter Description
@@ -1717,7 +1700,7 @@ img { max-width: 100%; }
palette 16-entry packed color palette
blinkVisible false = hide blinking characters
cursorCol Column for inverted text cursor (-1 = none)
-drawFocusRect
+drawFocusRect
void drawFocusRect(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);Draw a 1px dotted rectangle (alternating pixels). Used for keyboard focus indicators, matching the Windows 3.x focus rectangle convention.
Parameter Description
@@ -1726,7 +1709,7 @@ img { max-width: 100%; }
ops Blit operations vtable
x, y, w, h Focus rectangle bounds
color Dot color (packed)
-drawHLine
+drawHLine
void drawHLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, uint32_t color);Draw a horizontal line (1px tall).
Parameter Description
@@ -1736,7 +1719,7 @@ img { max-width: 100%; }
x, y Start position
w Width in pixels
color Packed pixel color
-drawVLine
+drawVLine
void drawVLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t h, uint32_t color);Draw a vertical line (1px wide).
Parameter Description
@@ -1749,41 +1732,40 @@ img { max-width: 100%; }
dvxComp.h -- Layer 3: Dirty Rectangle Compositor
-dvxComp.h -- Layer 3: Dirty Rectangle Compositor
Tracks changed screen regions and ensures only dirty regions are redrawn and flushed to video memory. The compositing pipeline: mark dirty, merge overlapping rects, redraw desktop + windows (back-to-front, painter's algorithm), flush to LFB.
-dirtyListInit
+dirtyListInit
void dirtyListInit(DirtyListT *dl);Zero the dirty rect count. Called at the start of each frame.
Parameter Description --------- ----------- dl Dirty list to initialize-
dirtyListAdd
+dirtyListAdd
void dirtyListAdd(DirtyListT *dl, int32_t x, int32_t y, int32_t w, int32_t h);Enqueue a dirty rectangle. Grows dynamically; triggers merge at a soft capacity limit.
Parameter Description --------- ----------- dl Dirty list x, y, w, h Dirty rectangle in screen coordinates-
dirtyListMerge
+dirtyListMerge
void dirtyListMerge(DirtyListT *dl);Consolidate the dirty list by merging overlapping and adjacent rects. Uses iterative pairwise merge: if combining two rects does not increase total area beyond a threshold, they are merged. Reduces compositor passes and LFB flush operations.
Parameter Description --------- ----------- dl Dirty list to merge-
dirtyListClear
+dirtyListClear
void dirtyListClear(DirtyListT *dl);Reset the dirty list to empty (sets count to 0).
Parameter Description --------- ----------- dl Dirty list to clear-
flushRect
+flushRect
void flushRect(DisplayT *d, const RectT *r);Copy a rectangle from the system RAM backbuffer to the LFB (video memory). This is the only place the real framebuffer is written. Uses platform-specific fast copy (rep movsd on DOS) for each scanline.
Parameter Description --------- ----------- d Display context r Rectangle to flush-
rectIntersect
+rectIntersect
bool rectIntersect(const RectT *a, const RectT *b, RectT *result);Compute the intersection of two rectangles.
Parameter Description
@@ -1791,7 +1773,7 @@ img { max-width: 100%; }
a, b Input rectangles
result Output: intersection rectangle (valid only when return is true)
Returns: true if the rectangles overlap, false if disjoint.
-rectIsEmpty
+rectIsEmpty
bool rectIsEmpty(const RectT *r);Test whether a rectangle has zero or negative area.
Parameter Description
@@ -1801,17 +1783,16 @@ img { max-width: 100%; }
dvxWm.h -- Layer 4: Window Manager
-dvxWm.h -- Layer 4: Window Manager
Manages the window lifecycle, Z-order stack, chrome drawing, hit testing, and interactive operations (drag, resize, scroll). The WM owns window geometry and chrome; content is owned by the application via callbacks or the widget system.
-Initialization
-wmInit
+Initialization
+wmInit
void wmInit(WindowStackT *stack);Zero the window stack. Must be called before any other WM function.
Parameter Description --------- ----------- stack Window stack to initialize-
Window Lifecycle
-wmCreateWindow
+Window Lifecycle
+wmCreateWindow
WindowT *wmCreateWindow(WindowStackT *stack, DisplayT *d, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);Allocate a new window, initialize its geometry and content buffer, and push it to the top of the Z-order stack. Returns with all callbacks NULL; the caller should set onPaint/onKey/etc. before the next event loop iteration.
Parameter Description
@@ -1823,15 +1804,15 @@ img { max-width: 100%; }
w, h Initial outer frame dimensions
resizable true = allow user resize
Returns: Pointer to new WindowT, or NULL on failure.
-wmDestroyWindow
+wmDestroyWindow
void wmDestroyWindow(WindowStackT *stack, WindowT *win);Free the window's content buffer and all attached resources (menu bar, scrollbars, widget tree), remove it from the stack, and dirty the vacated region.
Parameter Description --------- ----------- stack Window stack win Window to destroy-
Z-Order and Focus
-wmRaiseWindow
+Z-Order and Focus
+wmRaiseWindow
void wmRaiseWindow(WindowStackT *stack, DirtyListT *dl, int32_t idx);Move window at stack index idx to the top of the Z-order. Dirties both old and new top positions so overlapping windows get repainted.
Parameter Description
@@ -1839,7 +1820,7 @@ img { max-width: 100%; }
stack Window stack
dl Dirty list for repaint marking
idx Stack index of window to raise
-wmSetFocus
+wmSetFocus
void wmSetFocus(WindowStackT *stack, DirtyListT *dl, int32_t idx);Transfer keyboard focus to the window at stack index idx. Unfocuses the previously focused window and dirties both title bars.
Parameter Description
@@ -1847,14 +1828,14 @@ img { max-width: 100%; }
stack Window stack
dl Dirty list
idx Stack index of window to focus
-Geometry
-wmUpdateContentRect
+Geometry
+wmUpdateContentRect
void wmUpdateContentRect(WindowT *win);Recompute contentX/Y/W/H from the window's outer frame dimensions, accounting for chrome borders, title bar, menu bar, and scrollbars. Must be called after any change to frame size or chrome configuration.
Parameter Description --------- ----------- win Window to update-
wmReallocContentBuf
+wmReallocContentBuf
int32_t wmReallocContentBuf(WindowT *win, const DisplayT *d);Reallocate the per-window content backbuffer to match current contentW/H. Old buffer contents are lost; caller should trigger a full repaint via onPaint afterward.
Parameter Description
@@ -1862,28 +1843,28 @@ img { max-width: 100%; }
win Window to reallocate
d Display context (for bytes-per-pixel)
Returns: 0 on success, -1 on allocation failure.
-wmMinWindowSize
+wmMinWindowSize
void wmMinWindowSize(const WindowT *win, int32_t *minW, int32_t *minH);Get the minimum window size. Accounts for chrome, gadgets, and menu bar.
Parameter Description --------- ----------- win Window minW, minH Output: minimum width and height-
Menu Bar
-wmAddMenuBar
+Menu Bar
+wmAddMenuBar
MenuBarT *wmAddMenuBar(WindowT *win);Allocate and attach a menu bar to a window. Adjusts content area to make room (CHROME_MENU_HEIGHT pixels). One menu bar per window.
Parameter Description --------- ----------- win Window to add menu bar to
Returns: Pointer to the new MenuBarT.
-wmDestroyMenuBar
+wmDestroyMenuBar
void wmDestroyMenuBar(WindowT *win);Free the menu bar and reclaim the content area.
Parameter Description --------- ----------- win Window to remove menu bar from-
wmAddMenu
+wmAddMenu
MenuT *wmAddMenu(MenuBarT *bar, const char *label);Append a dropdown menu to the menu bar. The label supports & accelerator markers (e.g. "&File").
Parameter Description
@@ -1891,7 +1872,7 @@ img { max-width: 100%; }
bar Menu bar
label Menu label text
Returns: Pointer to the new MenuT to populate with items.
-wmAddMenuItem
+wmAddMenuItem
void wmAddMenuItem(MenuT *menu, const char *label, int32_t id);Append a clickable item to a menu. The id is passed to the window's onMenu callback when selected.
Parameter Description
@@ -1899,7 +1880,7 @@ img { max-width: 100%; }
menu Menu to append to
label Item label (supports & markers)
id Application-defined command ID
-wmAddMenuCheckItem
+wmAddMenuCheckItem
void wmAddMenuCheckItem(MenuT *menu, const char *label, int32_t id, bool checked);Add a checkbox-style menu item. Check state toggles on click; rendered with a checkmark glyph.
Parameter Description
@@ -1908,7 +1889,7 @@ img { max-width: 100%; }
label Item label
id Command ID
checked Initial checked state
-wmAddMenuRadioItem
+wmAddMenuRadioItem
void wmAddMenuRadioItem(MenuT *menu, const char *label, int32_t id, bool checked);Add a radio-style menu item. Radio groups are defined implicitly by consecutive radio items; selecting one unchecks the others in the group.
Parameter Description
@@ -1917,13 +1898,13 @@ img { max-width: 100%; }
label Item label
id Command ID
checked Initial checked state
-wmAddMenuSeparator
+wmAddMenuSeparator
void wmAddMenuSeparator(MenuT *menu);Insert a horizontal separator line. Separators are not interactive.
Parameter Description --------- ----------- menu Menu to append separator to-
wmMenuItemIsChecked
+wmMenuItemIsChecked
bool wmMenuItemIsChecked(MenuBarT *bar, int32_t id);Query the checked state of a menu item by command ID. Searches all menus in the bar.
Parameter Description
@@ -1931,7 +1912,7 @@ img { max-width: 100%; }
bar Menu bar
id Command ID to query
Returns: true if checked.
-wmMenuItemSetChecked
+wmMenuItemSetChecked
void wmMenuItemSetChecked(MenuBarT *bar, int32_t id, bool checked);Set the checked state of a menu item by command ID. For radio items, setting checked=true also unchecks other radio items in the same group.
Parameter Description
@@ -1939,7 +1920,7 @@ img { max-width: 100%; }
bar Menu bar
id Command ID
checked New checked state
-wmMenuItemSetEnabled
+wmMenuItemSetEnabled
void wmMenuItemSetEnabled(MenuBarT *bar, int32_t id, bool enabled);Enable or disable a menu item by command ID.
Parameter Description
@@ -1947,7 +1928,7 @@ img { max-width: 100%; }
bar Menu bar
id Command ID
enabled true = enabled, false = grayed out
-wmAddSubMenu
+wmAddSubMenu
MenuT *wmAddSubMenu(MenuT *parentMenu, const char *label);Create a cascading submenu attached to a parent menu. The child MenuT is heap-allocated and freed when the parent window is destroyed.
Parameter Description
@@ -1955,18 +1936,18 @@ img { max-width: 100%; }
parentMenu Parent menu to attach submenu to
label Submenu label text
Returns: Pointer to the child MenuT, or NULL on allocation failure.
-wmCreateMenu
+wmCreateMenu
MenuT *wmCreateMenu(void);Allocate a heap-resident MenuT for use as a context menu (right-click). Unlike menu bar menus, context menus are standalone allocations. Free with wmFreeMenu().
Returns: Pointer to the new MenuT.
-wmFreeMenu
+wmFreeMenu
void wmFreeMenu(MenuT *menu);Free a standalone menu allocated with wmCreateMenu(). Also frees any heap-allocated submenu children recursively.
Parameter Description --------- ----------- menu Menu to free-
Scrollbars
-wmAddVScrollbar
+Scrollbars
+wmAddVScrollbar
ScrollbarT *wmAddVScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);Attach a vertical scrollbar to the right edge of the window's content area. Shrinks contentW by SCROLLBAR_WIDTH pixels.
Parameter Description
@@ -1975,7 +1956,7 @@ img { max-width: 100%; }
min, max Scroll value range
pageSize Visible portion (controls thumb size)
Returns: Pointer to the new ScrollbarT.
-wmAddHScrollbar
+wmAddHScrollbar
ScrollbarT *wmAddHScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);Attach a horizontal scrollbar to the bottom edge. Shrinks contentH by SCROLLBAR_WIDTH pixels.
Parameter Description
@@ -1984,8 +1965,8 @@ img { max-width: 100%; }
min, max Scroll value range
pageSize Visible portion
Returns: Pointer to the new ScrollbarT.
-Drawing
-wmDrawChrome
+Drawing
+wmDrawChrome
void wmDrawChrome(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);Draw the window frame: outer bevel, title bar with text, close/minimize/maximize gadgets, and menu bar if present. Drawing is clipped to the intersection with clipTo.
Parameter Description
@@ -1996,7 +1977,7 @@ img { max-width: 100%; }
colors Color scheme
win Window to draw chrome for
clipTo Dirty rectangle to clip drawing to
-wmDrawContent
+wmDrawContent
void wmDrawContent(DisplayT *d, const BlitOpsT *ops, WindowT *win, const RectT *clipTo);Blit the window's content backbuffer into the display backbuffer, clipped to the dirty rect. Pure copy operation (no drawing).
Parameter Description
@@ -2005,7 +1986,7 @@ img { max-width: 100%; }
ops Blit operations vtable
win Window
clipTo Dirty rectangle
-wmDrawScrollbars
+wmDrawScrollbars
void wmDrawScrollbars(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);Draw scrollbars (track, arrows, proportional thumb) for a window. Drawn after content so scrollbars overlay the content area edge.
Parameter Description
@@ -2015,7 +1996,7 @@ img { max-width: 100%; }
colors Color scheme
win Window
clipTo Dirty rectangle
-wmDrawMinimizedIcons
+wmDrawMinimizedIcons
void wmDrawMinimizedIcons(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, const WindowStackT *stack, const RectT *clipTo);Draw icons for all minimized windows along the bottom of the screen. Each icon shows a scaled preview of the window's content with a beveled border.
Parameter Description
@@ -2025,8 +2006,8 @@ img { max-width: 100%; }
colors Color scheme
stack Window stack
clipTo Dirty rectangle
-Hit Testing
-wmHitTest
+Hit Testing
+wmHitTest
int32_t wmHitTest(const WindowStackT *stack, int32_t mx, int32_t my, int32_t *hitPart);Determine which window and chrome region is under the given screen coordinates. Iterates front-to-back (highest Z first) so the topmost window wins.
Parameter Description
@@ -2035,7 +2016,7 @@ img { max-width: 100%; }
mx, my Screen coordinates
hitPart Output: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, etc.
Returns: Stack index of hit window, or -1 for desktop.
-wmResizeEdgeHit
+wmResizeEdgeHit
int32_t wmResizeEdgeHit(const WindowT *win, int32_t mx, int32_t my);Determine which edge(s) of a window's border zone are targeted for resize.
Parameter Description
@@ -2043,7 +2024,7 @@ img { max-width: 100%; }
win Window
mx, my Screen coordinates
Returns: Bitmask of RESIZE_LEFT / RESIZE_RIGHT / RESIZE_TOP / RESIZE_BOTTOM.
-wmMinimizedIconHit
+wmMinimizedIconHit
int32_t wmMinimizedIconHit(const WindowStackT *stack, const DisplayT *d, int32_t mx, int32_t my);Hit-test minimized icons at the bottom of the screen.
Parameter Description
@@ -2052,8 +2033,8 @@ img { max-width: 100%; }
d Display context
mx, my Screen coordinates
Returns: Stack index of the minimized window, or -1.
-Drag and Resize
-wmDragBegin
+Drag and Resize
+wmDragBegin
void wmDragBegin(WindowStackT *stack, int32_t idx, int32_t mouseX, int32_t mouseY);Begin a window drag operation. Records the mouse offset from the window origin.
Parameter Description
@@ -2061,7 +2042,7 @@ img { max-width: 100%; }
stack Window stack
idx Stack index of window to drag
mouseX/Y Current mouse position
-wmDragMove
+wmDragMove
void wmDragMove(WindowStackT *stack, DirtyListT *dl, int32_t mouseX, int32_t mouseY, int32_t screenW, int32_t screenH);Update window position during an active drag. Dirties both old and new positions.
Parameter Description
@@ -2070,13 +2051,13 @@ img { max-width: 100%; }
dl Dirty list
mouseX/Y Current mouse position
screenW/H Screen dimensions (for clamping)
-wmDragEnd
+wmDragEnd
void wmDragEnd(WindowStackT *stack);End the current drag operation. Clears dragWindow state.
Parameter Description --------- ----------- stack Window stack-
wmResizeBegin
+wmResizeBegin
void wmResizeBegin(WindowStackT *stack, int32_t idx, int32_t edge, int32_t mouseX, int32_t mouseY);Begin a window resize operation. Records which edge(s) are being dragged.
Parameter Description
@@ -2085,7 +2066,7 @@ img { max-width: 100%; }
idx Stack index
edge Bitmask of RESIZE_xxx flags
mouseX/Y Current mouse position
-wmResizeMove
+wmResizeMove
void wmResizeMove(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, int32_t *mouseX, int32_t *mouseY);Update window dimensions during an active resize. Enforces MIN_WINDOW_W/H and maxW/maxH constraints. Reallocates content buffer and calls onResize if size changed. mouseX/mouseY are in/out: clamped on return for cursor warping.
Parameter Description
@@ -2094,14 +2075,14 @@ img { max-width: 100%; }
dl Dirty list
d Display context
mouseX/Y In/out: mouse position (clamped on return)
-wmResizeEnd
+wmResizeEnd
void wmResizeEnd(WindowStackT *stack);End the current resize operation. Clears resizeWindow state.
Parameter Description --------- ----------- stack Window stack-
Scrollbar Interaction
-wmScrollbarClick
+Scrollbar Interaction
+wmScrollbarClick
void wmScrollbarClick(WindowStackT *stack, DirtyListT *dl, int32_t idx, int32_t orient, int32_t mx, int32_t my);Handle an initial click on a scrollbar. Determines what was hit (arrows, trough, or thumb) and either adjusts the value immediately or begins a thumb drag.
Parameter Description
@@ -2111,7 +2092,7 @@ img { max-width: 100%; }
idx Stack index of window
orient SCROLL_VERTICAL or SCROLL_HORIZONTAL
mx, my Click screen coordinates
-wmScrollbarDrag
+wmScrollbarDrag
void wmScrollbarDrag(WindowStackT *stack, DirtyListT *dl, int32_t mx, int32_t my);Update the scroll value during an active thumb drag. Maps mouse position along the track to a proportional scroll value.
Parameter Description
@@ -2119,14 +2100,14 @@ img { max-width: 100%; }
stack Window stack
dl Dirty list
mx, my Current mouse position
-wmScrollbarEnd
+wmScrollbarEnd
void wmScrollbarEnd(WindowStackT *stack);End an active scrollbar thumb drag.
Parameter Description --------- ----------- stack Window stack-
Minimize / Maximize / Restore
-wmMaximize
+Minimize / Maximize / Restore
+wmMaximize
void wmMaximize(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);Maximize a window. Saves current geometry, then expands to screen or maxW/maxH bounds.
Parameter Description
@@ -2135,7 +2116,7 @@ img { max-width: 100%; }
dl Dirty list
d Display context
win Window to maximize
-wmMinimize
+wmMinimize
void wmMinimize(WindowStackT *stack, DirtyListT *dl, WindowT *win);Minimize a window. Hides the window and shows an icon at the bottom of the screen.
Parameter Description
@@ -2143,7 +2124,7 @@ img { max-width: 100%; }
stack Window stack
dl Dirty list
win Window to minimize
-wmRestore
+wmRestore
void wmRestore(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);Restore a maximized window to its pre-maximize geometry.
Parameter Description
@@ -2152,7 +2133,7 @@ img { max-width: 100%; }
dl Dirty list
d Display context
win Maximized window to restore
-wmRestoreMinimized
+wmRestoreMinimized
void wmRestoreMinimized(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);Restore a minimized window (show it again and remove the icon).
Parameter Description
@@ -2161,8 +2142,8 @@ img { max-width: 100%; }
dl Dirty list
d Display context
win Minimized window to restore
-Minimized Icon Layout
-wmMinimizedIconPos
+Minimized Icon Layout
+wmMinimizedIconPos
void wmMinimizedIconPos(const DisplayT *d, int32_t index, int32_t *x, int32_t *y);Compute the screen position of a minimized icon by ordinal index. Icons wrap into rows from bottom to top when the screen fills up.
Parameter Description
@@ -2170,7 +2151,7 @@ img { max-width: 100%; }
d Display context
index Ordinal index of the minimized icon
x, y Output: screen position
-wmMinimizedIconRect
+wmMinimizedIconRect
void wmMinimizedIconRect(const WindowStackT *stack, const DisplayT *d, int32_t *y, int32_t *h);Compute the screen rect covering all minimized icon rows. Used to dirty the icon area when windows are minimized or restored.
Parameter Description
@@ -2178,8 +2159,8 @@ img { max-width: 100%; }
stack Window stack
d Display context
y, h Output: vertical extent of icon area
-Miscellaneous
-wmSetTitle
+Miscellaneous
+wmSetTitle
void wmSetTitle(WindowT *win, DirtyListT *dl, const char *title);Set the window title and dirty the title bar for repaint.
Parameter Description
@@ -2187,7 +2168,7 @@ img { max-width: 100%; }
win Window
dl Dirty list
title New title text
-wmSetIcon
+wmSetIcon
int32_t wmSetIcon(WindowT *win, const char *path, const DisplayT *d);Load an icon image for a window from a file. Converts to display pixel format.
Parameter Description
@@ -2199,12 +2180,11 @@ img { max-width: 100%; }
dvxApp.h -- Layer 5: Application API
-dvxApp.h -- Layer 5: Application API
The topmost layer and the public-facing API. Aggregates all lower layers into a single AppContextT. Applications interact exclusively through dvx*() functions and window callbacks. The event loop follows a cooperative model: poll, dispatch, composite, yield.
-AppContextT
+AppContextT
Single monolithic context that owns all GUI state. Contains the display, window stack, dirty list, blit ops, font, color scheme, popup state, cursor state, mouse/keyboard state, tooltip state, wallpaper buffer, video mode list, and various configuration fields. Allocated on the caller's stack or statically.
-Initialization and Shutdown
-dvxInit
+Initialization and Shutdown
+dvxInit
int32_t dvxInit(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);Initialize the entire GUI stack: video mode, input devices, font, color scheme, cursor shapes, and internal state. Single entry point for starting a DVX application.
Parameter Description
@@ -2213,13 +2193,13 @@ img { max-width: 100%; }
requestedW/H Desired screen resolution
preferredBpp Preferred bits per pixel
Returns: 0 on success, negative on failure.
-dvxShutdown
+dvxShutdown
void dvxShutdown(AppContextT *ctx);Tear down the GUI stack in reverse order: destroy all windows, restore text mode, release input devices. Safe to call after a failed dvxInit().
Parameter Description --------- ----------- ctx Application context-
dvxChangeVideoMode
+dvxChangeVideoMode
int32_t dvxChangeVideoMode(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);Switch to a new video mode live. Reallocates the backbuffer, all window content buffers, repacks colors, rescales wallpaper, and repositions off-screen windows.
Parameter Description
@@ -2228,28 +2208,28 @@ img { max-width: 100%; }
requestedW/H New resolution
preferredBpp New bits per pixel
Returns: 0 on success, -1 on failure (old mode restored).
-Event Loop
-dvxRun
+Event Loop
+dvxRun
void dvxRun(AppContextT *ctx);Enter the main event loop. Polls input, dispatches events, composites dirty regions, and yields on each iteration. Returns when ctx->running becomes false.
Parameter Description --------- ----------- ctx Application context-
dvxUpdate
+dvxUpdate
bool dvxUpdate(AppContextT *ctx);Process exactly one frame of the event loop. For applications that integrate the GUI into their own main loop (e.g. polling serial ports between frames).
Parameter Description --------- ----------- ctx Application context
Returns: false when the GUI wants to exit.
-dvxQuit
+dvxQuit
void dvxQuit(AppContextT *ctx);Request exit from the main event loop (sets ctx->running = false).
Parameter Description --------- ----------- ctx Application context-
Window Management
-dvxCreateWindow
+Window Management
+dvxCreateWindow
WindowT *dvxCreateWindow(AppContextT *ctx, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);Create a window at an explicit screen position. The window is raised to the top, focused, and its entire region is dirtied.
Parameter Description
@@ -2260,7 +2240,7 @@ img { max-width: 100%; }
w, h Outer frame dimensions
resizable true = allow user resize
Returns: Pointer to new WindowT.
-dvxCreateWindowCentered
+dvxCreateWindowCentered
WindowT *dvxCreateWindowCentered(AppContextT *ctx, const char *title, int32_t w, int32_t h, bool resizable);Convenience wrapper that centers the window on screen.
Parameter Description
@@ -2270,42 +2250,42 @@ img { max-width: 100%; }
w, h Outer frame dimensions
resizable true = allow user resize
Returns: Pointer to new WindowT.
-dvxDestroyWindow
+dvxDestroyWindow
void dvxDestroyWindow(AppContextT *ctx, WindowT *win);Destroy a window, free all its resources, and dirty its former region.
Parameter Description --------- ----------- ctx Application context win Window to destroy-
dvxRaiseWindow
+dvxRaiseWindow
void dvxRaiseWindow(AppContextT *ctx, WindowT *win);Raise a window to the top of the Z-order and give it focus.
Parameter Description --------- ----------- ctx Application context win Window to raise-
dvxFitWindow
+dvxFitWindow
void dvxFitWindow(AppContextT *ctx, WindowT *win);Resize a window to exactly fit its widget tree's computed minimum size (plus chrome). Used for dialog boxes and fixed-layout windows.
Parameter Description --------- ----------- ctx Application context win Window to fit-
dvxFitWindowW
+dvxFitWindowW
void dvxFitWindowW(AppContextT *ctx, WindowT *win);Resize window width only to fit widget tree's minimum width (plus chrome).
Parameter Description --------- ----------- ctx Application context win Window to fit-
dvxFitWindowH
+dvxFitWindowH
void dvxFitWindowH(AppContextT *ctx, WindowT *win);Resize window height only to fit widget tree's minimum height (plus chrome).
Parameter Description --------- ----------- ctx Application context win Window to fit-
dvxResizeWindow
+dvxResizeWindow
void dvxResizeWindow(AppContextT *ctx, WindowT *win, int32_t newW, int32_t newH);Programmatically resize a window to the specified outer dimensions.
Parameter Description
@@ -2313,36 +2293,36 @@ img { max-width: 100%; }
ctx Application context
win Window to resize
newW, newH New outer frame dimensions
-dvxMinimizeWindow
+dvxMinimizeWindow
void dvxMinimizeWindow(AppContextT *ctx, WindowT *win);Minimize a window (show as icon at bottom of screen).
Parameter Description --------- ----------- ctx Application context win Window to minimize-
dvxMaximizeWindow
+dvxMaximizeWindow
void dvxMaximizeWindow(AppContextT *ctx, WindowT *win);Maximize a window (expand to fill screen or maxW/maxH).
Parameter Description --------- ----------- ctx Application context win Window to maximize-
dvxHideWindow
+dvxHideWindow
void dvxHideWindow(AppContextT *ctx, WindowT *win);Hide a window without destroying it. Marks the exposed region dirty.
Parameter Description --------- ----------- ctx Application context win Window to hide-
dvxShowWindow
+dvxShowWindow
void dvxShowWindow(AppContextT *ctx, WindowT *win);Show a previously hidden window. Marks its region dirty for repaint.
Parameter Description --------- ----------- ctx Application context win Window to show-
Invalidation
-dvxInvalidateRect
+Invalidation
+dvxInvalidateRect
void dvxInvalidateRect(AppContextT *ctx, WindowT *win, int32_t x, int32_t y, int32_t w, int32_t h);Mark a sub-region of a window's content area as needing repaint. Coordinates are relative to the content area, not the screen. Triggers onPaint during the next composite pass.
Parameter Description
@@ -2350,15 +2330,15 @@ img { max-width: 100%; }
ctx Application context
win Window
x, y, w, h Dirty rectangle in content-relative coordinates
-dvxInvalidateWindow
+dvxInvalidateWindow
void dvxInvalidateWindow(AppContextT *ctx, WindowT *win);Mark the entire window content area as dirty.
Parameter Description --------- ----------- ctx Application context win Window to invalidate-
Window Properties
-dvxSetTitle
+Window Properties
+dvxSetTitle
void dvxSetTitle(AppContextT *ctx, WindowT *win, const char *title);Set a window's title text and dirty the title bar.
Parameter Description
@@ -2366,7 +2346,7 @@ img { max-width: 100%; }
ctx Application context
win Window
title New title text
-dvxSetWindowIcon
+dvxSetWindowIcon
int32_t dvxSetWindowIcon(AppContextT *ctx, WindowT *win, const char *path);Load an icon for a window from an image file.
Parameter Description
@@ -2375,43 +2355,43 @@ img { max-width: 100%; }
win Window
path Image file path
Returns: 0 on success, -1 on failure.
-dvxSetBusy
+dvxSetBusy
void dvxSetBusy(AppContextT *ctx, bool busy);Set or clear busy state. While busy, the hourglass cursor is shown and input is blocked.
Parameter Description --------- ----------- ctx Application context busy true = show hourglass, false = normal-
Accessors
-dvxGetFont
+Accessors
+dvxGetFont
const BitmapFontT *dvxGetFont(const AppContextT *ctx);Get a pointer to the default font.
Parameter Description --------- ----------- ctx Application context
Returns: Pointer to the active BitmapFontT.
-dvxGetColors
+dvxGetColors
const ColorSchemeT *dvxGetColors(const AppContextT *ctx);Get a pointer to the current color scheme.
Parameter Description --------- ----------- ctx Application context
Returns: Pointer to the active ColorSchemeT.
-dvxGetDisplay
+dvxGetDisplay
DisplayT *dvxGetDisplay(AppContextT *ctx);Get a pointer to the display context.
Parameter Description --------- ----------- ctx Application context
Returns: Pointer to the DisplayT.
-dvxGetBlitOps
+dvxGetBlitOps
const BlitOpsT *dvxGetBlitOps(const AppContextT *ctx);Get a pointer to the blit operations vtable.
Parameter Description --------- ----------- ctx Application context
Returns: Pointer to the active BlitOpsT.
-dvxGetVideoModes
+dvxGetVideoModes
const VideoModeInfoT *dvxGetVideoModes(const AppContextT *ctx, int32_t *count);Return the list of available video modes enumerated at init time.
Parameter Description
@@ -2419,8 +2399,8 @@ img { max-width: 100%; }
ctx Application context
count Output: number of mode entries
Returns: Pointer to the VideoModeInfoT array.
-Color Scheme
-dvxSetColor
+Color Scheme
+dvxSetColor
void dvxSetColor(AppContextT *ctx, ColorIdE id, uint8_t r, uint8_t g, uint8_t b);Set a single color by ID. Repacks to native pixel format and invalidates the entire screen.
Parameter Description
@@ -2428,7 +2408,7 @@ img { max-width: 100%; }
ctx Application context
id Color ID (ColorIdE)
r, g, b RGB values (0-255)
-dvxGetColor
+dvxGetColor
void dvxGetColor(const AppContextT *ctx, ColorIdE id, uint8_t *r, uint8_t *g, uint8_t *b);Get a color's RGB values by ID.
Parameter Description
@@ -2436,19 +2416,19 @@ img { max-width: 100%; }
ctx Application context
id Color ID (ColorIdE)
r, g, b Output: RGB values
-dvxApplyColorScheme
+dvxApplyColorScheme
void dvxApplyColorScheme(AppContextT *ctx);Apply all colors from ctx->colorRgb[] at once (repack + full repaint).
Parameter Description --------- ----------- ctx Application context-
dvxResetColorScheme
+dvxResetColorScheme
void dvxResetColorScheme(AppContextT *ctx);Reset all colors to the built-in defaults and repaint.
Parameter Description --------- ----------- ctx Application context-
dvxLoadTheme
+dvxLoadTheme
bool dvxLoadTheme(AppContextT *ctx, const char *filename);Load a theme file (INI format with [colors] section) and apply it.
Parameter Description
@@ -2456,7 +2436,7 @@ img { max-width: 100%; }
ctx Application context
filename Path to theme INI file
Returns: true on success.
-dvxSaveTheme
+dvxSaveTheme
bool dvxSaveTheme(const AppContextT *ctx, const char *filename);Save the current color scheme to a theme file.
Parameter Description
@@ -2464,22 +2444,22 @@ img { max-width: 100%; }
ctx Application context
filename Output file path
Returns: true on success.
-dvxColorName
+dvxColorName
const char *dvxColorName(ColorIdE id);Return the INI key name for a color ID (e.g. "desktop", "windowFace").
Parameter Description --------- ----------- id Color ID
Returns: Static string.
-dvxColorLabel
+dvxColorLabel
const char *dvxColorLabel(ColorIdE id);Return a human-readable display label (e.g. "Desktop", "Cursor Color").
Parameter Description --------- ----------- id Color ID
Returns: Static string.
-Wallpaper
-dvxSetWallpaper
+Wallpaper
+dvxSetWallpaper
bool dvxSetWallpaper(AppContextT *ctx, const char *path);Load and apply a wallpaper image using the current wallpaperMode (stretch/tile/center). Pass NULL to clear the wallpaper.
Parameter Description
@@ -2487,15 +2467,15 @@ img { max-width: 100%; }
ctx Application context
path Image file path, or NULL to clear
Returns: true on success.
-dvxSetWallpaperMode
+dvxSetWallpaperMode
void dvxSetWallpaperMode(AppContextT *ctx, WallpaperModeE mode);Change the wallpaper display mode and re-render. No effect if no wallpaper is loaded.
Parameter Description --------- ----------- ctx Application context mode WallpaperStretchE, WallpaperTileE, or WallpaperCenterE-
Mouse Configuration
-dvxSetMouseConfig
+Mouse Configuration
+dvxSetMouseConfig
void dvxSetMouseConfig(AppContextT *ctx, int32_t wheelDir, int32_t dblClickMs, int32_t accelThreshold);Configure mouse behavior.
Parameter Description
@@ -2504,18 +2484,18 @@ img { max-width: 100%; }
wheelDir 1 = normal, -1 = reversed
dblClickMs Double-click speed in milliseconds (e.g. 500)
accelThreshold Double-speed threshold in mickeys/sec (0 = don't change)
-Accelerators
-dvxCreateAccelTable
+Accelerators
+dvxCreateAccelTable
AccelTableT *dvxCreateAccelTable(void);Allocate a new accelerator table. Attach to a window via win->accelTable.
Returns: Pointer to new AccelTableT.
-dvxFreeAccelTable
+dvxFreeAccelTable
void dvxFreeAccelTable(AccelTableT *table);Free an accelerator table and its entries.
Parameter Description --------- ----------- table Table to free-
dvxAddAccel
+dvxAddAccel
void dvxAddAccel(AccelTableT *table, int32_t key, int32_t modifiers, int32_t cmdId);Register a keyboard shortcut. On match, fires the window's onMenu callback with cmdId.
Parameter Description
@@ -2524,33 +2504,33 @@ img { max-width: 100%; }
key ASCII character or KEY_Fxx constant
modifiers Bitmask of ACCEL_CTRL / ACCEL_SHIFT / ACCEL_ALT
cmdId Command ID passed to onMenu
-Window Arrangement
-dvxCascadeWindows
+Window Arrangement
+dvxCascadeWindows
void dvxCascadeWindows(AppContextT *ctx);Cascade all visible, non-minimized windows. Each is offset diagonally by the title bar height.
Parameter Description --------- ----------- ctx Application context-
dvxTileWindows
+dvxTileWindows
void dvxTileWindows(AppContextT *ctx);Arrange visible windows in an NxM grid filling the screen.
Parameter Description --------- ----------- ctx Application context-
dvxTileWindowsH
+dvxTileWindowsH
void dvxTileWindowsH(AppContextT *ctx);Tile windows horizontally (side by side, equal width, full height).
Parameter Description --------- ----------- ctx Application context-
dvxTileWindowsV
+dvxTileWindowsV
void dvxTileWindowsV(AppContextT *ctx);Tile windows vertically (stacked, full width, equal height).
Parameter Description --------- ----------- ctx Application context-
Image I/O
-dvxLoadImage
+Image I/O
+dvxLoadImage
uint8_t *dvxLoadImage(const AppContextT *ctx, const char *path, int32_t *outW, int32_t *outH, int32_t *outPitch);Load an image file (BMP, PNG, JPEG, GIF) and convert to the display's native pixel format. Caller must free with dvxFreeImage().
Parameter Description
@@ -2560,7 +2540,7 @@ img { max-width: 100%; }
outW, outH Output: image dimensions
outPitch Output: row pitch in bytes
Returns: Pixel buffer, or NULL on failure.
-dvxLoadImageFromMemory
+dvxLoadImageFromMemory
uint8_t *dvxLoadImageFromMemory(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch);Load an image from a memory buffer. Same output format as dvxLoadImage(). Caller must free with dvxFreeImage().
Parameter Description
@@ -2571,13 +2551,13 @@ img { max-width: 100%; }
outW, outH Output: image dimensions
outPitch Output: row pitch in bytes
Returns: Pixel buffer, or NULL on failure.
-dvxFreeImage
+dvxFreeImage
void dvxFreeImage(uint8_t *data);Free a pixel buffer returned by dvxLoadImage() or dvxLoadImageFromMemory().
Parameter Description --------- ----------- data Buffer to free-
dvxImageInfo
+dvxImageInfo
bool dvxImageInfo(const char *path, int32_t *outW, int32_t *outH);Query image dimensions without decoding the full file.
Parameter Description
@@ -2585,7 +2565,7 @@ img { max-width: 100%; }
path Image file path
outW, outH Output: image dimensions
Returns: true on success.
-dvxSaveImage
+dvxSaveImage
int32_t dvxSaveImage(const AppContextT *ctx, const uint8_t *data, int32_t w, int32_t h, int32_t pitch, const char *path);Save native-format pixel data to a PNG file.
Parameter Description
@@ -2596,8 +2576,8 @@ img { max-width: 100%; }
pitch Row pitch in bytes
path Output file path
Returns: 0 on success, -1 on failure.
-Screenshots
-dvxScreenshot
+Screenshots
+dvxScreenshot
int32_t dvxScreenshot(AppContextT *ctx, const char *path);Save the entire screen (backbuffer contents) to a PNG file. Converts from native pixel format to RGB.
Parameter Description
@@ -2605,7 +2585,7 @@ img { max-width: 100%; }
ctx Application context
path Output PNG file path
Returns: 0 on success, -1 on failure.
-dvxWindowScreenshot
+dvxWindowScreenshot
int32_t dvxWindowScreenshot(AppContextT *ctx, WindowT *win, const char *path);Save a window's content to a PNG file.
Parameter Description
@@ -2614,23 +2594,23 @@ img { max-width: 100%; }
win Window
path Output PNG file path
Returns: 0 on success, -1 on failure.
-Clipboard
-dvxClipboardCopy
+Clipboard
+dvxClipboardCopy
void dvxClipboardCopy(const char *text, int32_t len);Copy text to the process-wide clipboard buffer. Simple static buffer (not inter-process).
Parameter Description --------- ----------- text Text to copy len Length in bytes-
dvxClipboardGet
+dvxClipboardGet
const char *dvxClipboardGet(int32_t *outLen);Retrieve the current clipboard contents. Returns a pointer to the internal buffer (valid until the next dvxClipboardCopy), or NULL if empty.
Parameter Description --------- ----------- outLen Output: length of clipboard text
Returns: Clipboard text, or NULL.
-Resource Loading
-dvxResLoadIcon
+Resource Loading
+dvxResLoadIcon
uint8_t *dvxResLoadIcon(AppContextT *ctx, const char *dxePath, const char *resName, int32_t *outW, int32_t *outH, int32_t *outPitch);Load an icon/image resource from a DXE file and decode to native pixel format. Caller must free with dvxFreeImage().
Parameter Description
@@ -2641,7 +2621,7 @@ img { max-width: 100%; }
outW, outH Output: image dimensions
outPitch Output: row pitch
Returns: Pixel buffer, or NULL if not found.
-dvxResLoadText
+dvxResLoadText
bool dvxResLoadText(const char *dxePath, const char *resName, char *buf, int32_t bufSize);Load a text resource from a DXE file into a caller-provided buffer. Null-terminated and truncated to fit bufSize.
Parameter Description
@@ -2651,7 +2631,7 @@ img { max-width: 100%; }
buf Output buffer
bufSize Buffer capacity
Returns: true on success.
-dvxResLoadData
+dvxResLoadData
void *dvxResLoadData(const char *dxePath, const char *resName, uint32_t *outSize);Load a raw binary resource from a DXE file. Returns a malloc'd buffer that the caller must free.
Parameter Description
@@ -2660,8 +2640,8 @@ img { max-width: 100%; }
resName Resource name
outSize Output: data size in bytes
Returns: Data buffer, or NULL if not found.
-Utilities
-dvxTextHash
+Utilities
+dvxTextHash
uint32_t dvxTextHash(const char *text);Compute a djb2-xor hash for cheap dirty detection. Compare at save time with the current hash to detect changes without a shadow copy. Not cryptographic.
Parameter Description
@@ -2671,9 +2651,8 @@ img { max-width: 100%; }
dvxWidget.h -- Widget System
-dvxWidget.h -- Widget System
Retained-mode widget toolkit layered on the DVX window manager. Widgets form a tree (parent-child) rooted at a per-window VBox container. Layout is automatic: measure minimum sizes bottom-up, then allocate space top-down with flexbox-like weighted distribution. Widget types are registered dynamically at runtime via DXE plugins.
-WidgetT Structure
+WidgetT Structure
Core widget structure. Generic across all widget types; type-specific data lives in the void *data pointer managed by each widget's DXE.
Field Description
----- -----------
@@ -2711,13 +2690,13 @@ img { max-width: 100%; }
onMouseMove(WidgetT *w, int32_t btn, int32_t x, int32_t y) Mouse moved
onScroll(WidgetT *w, int32_t delta) Mouse wheel
onValidate(WidgetT *w) Return false to cancel a write
-Size Specification Macros
+Size Specification Macros
Macro Description ----- ----------- wgtPixels(v) Size in pixels wgtChars(v) Size in character widths (multiplied by charWidth at layout) wgtPercent(v) Size as percentage of parent dimension-
Widget Class Flags
+Widget Class Flags
Flag Description
---- -----------
WCLASS_FOCUSABLE Can receive keyboard focus (Tab navigation)
@@ -2733,8 +2712,8 @@ img { max-width: 100%; }
WCLASS_RELAYOUT_ON_SCROLL Full relayout on scrollbar drag
WCLASS_PRESS_RELEASE Click = press + release (Button, ImageButton)
WCLASS_ACCEL_WHEN_HIDDEN Accelerator matching works even when invisible
-Window Integration
-wgtInitWindow
+Window Integration
+wgtInitWindow
WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win);Initialize the widget system for a window. Creates a root VBox container that fills the content area, and installs callback handlers (onPaint, onMouse, onKey, onResize) for widget-based event dispatch. The window's userData is set to the AppContextT pointer.
Parameter Description
@@ -2742,79 +2721,79 @@ img { max-width: 100%; }
ctx Application context
win Window to initialize
Returns: Root VBox widget (add children to this).
-Widget Operations
-wgtGetContext
+Widget Operations
+wgtGetContext
AppContextT *wgtGetContext(const WidgetT *w);Walk from any widget up the tree to the root, then retrieve the AppContextT stored in the window's userData. Lets any widget access the full application context.
Parameter Description --------- ----------- w Any widget in the tree
Returns: Pointer to the AppContextT.
-wgtInvalidate
+wgtInvalidate
void wgtInvalidate(WidgetT *w);Mark a widget as needing both re-layout (measure + position) and repaint. Propagates upward to ancestors. Use after structural changes (adding/removing children, text changes that affect size).
Parameter Description --------- ----------- w Widget to invalidate-
wgtInvalidatePaint
+wgtInvalidatePaint
void wgtInvalidatePaint(WidgetT *w);Mark a widget as needing repaint only, without re-layout. Use for visual-only changes (checkbox toggle, selection highlight, cursor blink).
Parameter Description --------- ----------- w Widget to repaint-
wgtSetText
+wgtSetText
void wgtSetText(WidgetT *w, const char *text);Set widget text content (dispatches to the widget class's SET_TEXT handler).
Parameter Description --------- ----------- w Widget text New text-
wgtGetText
+wgtGetText
const char *wgtGetText(const WidgetT *w);Get the widget's current text content.
Parameter Description --------- ----------- w Widget
Returns: Text string (empty string if no handler).
-wgtSetEnabled
+wgtSetEnabled
void wgtSetEnabled(WidgetT *w, bool enabled);Enable or disable a widget. Disabled widgets are grayed out and do not receive input.
Parameter Description --------- ----------- w Widget enabled true = enabled, false = disabled-
wgtSetReadOnly
+wgtSetReadOnly
void wgtSetReadOnly(WidgetT *w, bool readOnly);Set read-only mode. Allows scrolling and selection but blocks editing.
Parameter Description --------- ----------- w Widget readOnly true = read-only-
wgtSetFocused
+wgtSetFocused
void wgtSetFocused(WidgetT *w);Set keyboard focus to a widget.
Parameter Description --------- ----------- w Widget to focus-
wgtGetFocused
+wgtGetFocused
WidgetT *wgtGetFocused(void);Get the currently focused widget.
Returns: Focused widget, or NULL.
-wgtSetVisible
+wgtSetVisible
void wgtSetVisible(WidgetT *w, bool visible);Show or hide a widget.
Parameter Description --------- ----------- w Widget visible true = visible, false = hidden-
wgtSetName
+wgtSetName
void wgtSetName(WidgetT *w, const char *name);Set a widget's name for lookup via wgtFind().
Parameter Description --------- ----------- w Widget name Name string (max MAX_WIDGET_NAME chars)-
wgtFind
+wgtFind
WidgetT *wgtFind(WidgetT *root, const char *name);Find a widget by name. Searches the subtree rooted at root.
Parameter Description
@@ -2822,28 +2801,28 @@ img { max-width: 100%; }
root Root of subtree to search
name Widget name to find
Returns: Matching widget, or NULL.
-wgtDestroy
+wgtDestroy
void wgtDestroy(WidgetT *w);Destroy a widget and all its children. Removes from parent's child list.
Parameter Description --------- ----------- w Widget to destroy-
wgtSetTooltip
+wgtSetTooltip
void wgtSetTooltip(WidgetT *w, const char *text);Set tooltip text for a widget. Pass NULL to remove. Caller owns the string and it must outlive the widget.
Parameter Description --------- ----------- w Widget text Tooltip text, or NULL-
widgetOnResize
+widgetOnResize
void widgetOnResize(WindowT *win, int32_t newW, int32_t newH);Default window resize handler installed by wgtInitWindow(). Re-evaluates scrollbars and relayouts the widget tree. Call from custom onResize handlers to chain to the widget system.
Parameter Description --------- ----------- win Window being resized newW, newH New content dimensions-
Layout
-wgtResolveSize
+Layout
+wgtResolveSize
int32_t wgtResolveSize(int32_t taggedSize, int32_t parentSize, int32_t charWidth);Decode a tagged size value (WGT_SIZE_PIXELS/CHARS/PERCENT) into a concrete pixel count. Returns 0 for a raw 0 input (meaning "auto").
Parameter Description
@@ -2852,7 +2831,7 @@ img { max-width: 100%; }
parentSize Parent dimension (for PERCENT mode)
charWidth Font character width (for CHARS mode)
Returns: Size in pixels.
-wgtLayout
+wgtLayout
void wgtLayout(WidgetT *root, int32_t availW, int32_t availH, const BitmapFontT *font);Execute the full two-pass layout algorithm. Pass 1 (bottom-up): compute minimum sizes. Pass 2 (top-down): allocate space with weighted distribution. Normally called automatically; exposed for cases where layout must be forced before the next paint.
Parameter Description
@@ -2860,7 +2839,7 @@ img { max-width: 100%; }
root Root widget
availW/H Available space
font Bitmap font (for character-based sizing)
-wgtPaint
+wgtPaint
void wgtPaint(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors);Paint the entire widget tree by depth-first traversal. Each widget's clip rect is set to its bounds. Overlays (popups, tooltips) are painted in a second pass on top.
Parameter Description
@@ -2870,63 +2849,63 @@ img { max-width: 100%; }
ops Blit operations vtable
font Bitmap font
colors Color scheme
-Debug
-wgtSetDebugLayout
+Debug
+wgtSetDebugLayout
void wgtSetDebugLayout(AppContextT *ctx, bool enabled);Draw colored borders around layout containers for debugging.
Parameter Description --------- ----------- ctx Application context enabled true = draw debug borders-
Dynamic Widget Registration
-wgtRegisterClass
+Dynamic Widget Registration
+wgtRegisterClass
int32_t wgtRegisterClass(const WidgetClassT *wclass);Register a new widget class at runtime. Appends to widgetClassTable. The WidgetClassT must remain valid for the lifetime of the process (typically static const in a DXE).
Parameter Description --------- ----------- wclass Widget class vtable to register
Returns: Assigned type ID.
-wgtRegisterApi
+wgtRegisterApi
void wgtRegisterApi(const char *name, const void *api);Register a widget API struct under a name. Each widget DXE registers its API during initialization. Callers retrieve it via wgtGetApi() and cast to the widget-specific type.
Parameter Description --------- ----------- name Widget type name (e.g. "button", "listbox") api Pointer to the widget's API struct-
wgtGetApi
+wgtGetApi
const void *wgtGetApi(const char *name);Retrieve a registered widget API struct by name.
Parameter Description --------- ----------- name Widget type name
Returns: Pointer to the API struct, or NULL if not found.
-Widget Interface Descriptors
-wgtRegisterIface
+Widget Interface Descriptors
+wgtRegisterIface
void wgtRegisterIface(const char *name, const WgtIfaceT *iface);Register an interface descriptor for a widget type. Used by the BASIC form runtime and IDE for generic property/method dispatch.
Parameter Description --------- ----------- name Widget type name iface Interface descriptor-
wgtGetIface
+wgtGetIface
const WgtIfaceT *wgtGetIface(const char *name);Retrieve an interface descriptor by widget type name.
Parameter Description --------- ----------- name Widget type name
Returns: Interface descriptor, or NULL.
-wgtFindByBasName
+wgtFindByBasName
const char *wgtFindByBasName(const char *basName);Find a widget type name by its VB-style name (e.g. "CommandButton" -> "button"). Case-insensitive search.
Parameter Description --------- ----------- basName VB-style widget name
Returns: Internal type name, or NULL.
-wgtIfaceCount
+wgtIfaceCount
int32_t wgtIfaceCount(void);Return the number of registered widget interfaces.
Returns: Count of registered interfaces.
-wgtIfaceAt
+wgtIfaceAt
const WgtIfaceT *wgtIfaceAt(int32_t idx, const char **outName);Get a registered widget interface by index.
Parameter Description
@@ -2934,28 +2913,28 @@ img { max-width: 100%; }
idx Index (0-based)
outName Output: type name
Returns: Interface descriptor.
-wgtIfaceGetPath
+wgtIfaceGetPath
const char *wgtIfaceGetPath(const char *name);Get the .wgt DXE file path for a registered widget.
Parameter Description --------- ----------- name Widget type name
Returns: File path string.
-wgtIfaceSetPath
+wgtIfaceSetPath
void wgtIfaceSetPath(const char *name, const char *path);Set the .wgt DXE file path for a registered widget (called by the loader).
Parameter Description --------- ----------- name Widget type name path DXE file path-
wgtIfaceGetPathIndex
+wgtIfaceGetPathIndex
int32_t wgtIfaceGetPathIndex(const char *name);Get the 1-based index of this widget within its .wgt file. Used to construct suffixed resource names (e.g. "name-2", "icon16-2").
Parameter Description --------- ----------- name Widget type name
Returns: 1-based index within the DXE file.
-Typed Dispatch Helpers
+Typed Dispatch Helpers
The following inline functions provide type-safe dispatch through the WidgetClassT handler table. Each checks for a non-NULL handler before calling.
Function Method ID Description
-------- --------- -----------
@@ -2984,12 +2963,11 @@ img { max-width: 100%; }
libtasks -- Cooperative Task Switching
-libtasks -- Cooperative Task Switching
Credit-based cooperative (non-preemptive) multitasking library for DOS protected mode (DJGPP/DPMI). Each task receives (priority + 1) credits per scheduling round. Tasks run round-robin, consuming one credit per turn. When all credits are exhausted, every ready task is refilled. Higher-priority tasks run proportionally more often but never starve lower ones.
Header: tasks/taskswitch.h
-Why Cooperative
+Why Cooperative
DOS is single-threaded with no kernel scheduler. DPMI provides no preemption primitives. The DVX GUI event model is inherently single-threaded: one compositor, one input queue, one window stack. Cooperative switching lets each task yield at safe points, avoiding synchronization primitives entirely.
-Error Codes
+Error Codes
Constant Value Description
-------- ----- -----------
TS_OK 0 Success
@@ -2998,7 +2976,7 @@ img { max-width: 100%; }
TS_ERR_FULL -3 Task array full (should not occur; array grows)
TS_ERR_NOMEM -4 Memory allocation failed
TS_ERR_STATE -5 Invalid state transition
-Constants
+Constants
Constant Value Description
-------- ----- -----------
TS_DEFAULT_STACK_SIZE 32768 Default stack size per task (32 KB)
@@ -3006,8 +2984,8 @@ img { max-width: 100%; }
TS_PRIORITY_LOW 0 Low priority (1 credit per round)
TS_PRIORITY_NORMAL 5 Normal priority (6 credits per round)
TS_PRIORITY_HIGH 10 High priority (11 credits per round)
-Types
-TaskStateE
+Types
+TaskStateE
Task scheduling state. Only Ready tasks participate in scheduling.
Value Description
----- -----------
@@ -3015,17 +2993,17 @@ img { max-width: 100%; }
TaskStateRunning Currently executing (cosmetic; marks active task)
TaskStatePaused Skipped by scheduler until explicitly resumed
TaskStateTerminated Slot available for reuse
-TaskEntryT
+TaskEntryT
typedef void (*TaskEntryT)(void *arg);Task entry point function signature. The void* argument lets the caller pass arbitrary context (e.g. a shell app descriptor).
-tsInit
+tsInit
int32_t tsInit(void);Initialize the task system. The calling context becomes task 0 (the main task). Task 0 is special: it cannot be killed or paused, and tsRecoverToMain() always returns control here. No separate stack is allocated for task 0; it uses the process stack directly.
Returns: TS_OK on success, TS_ERR_INIT if already initialized.
-tsShutdown
+tsShutdown
void tsShutdown(void);Shut down the task system and free all task stacks and internal storage. Safe to call even if tsInit() was never called.
-tsCreate
+tsCreate
int32_t tsCreate(const char *name, TaskEntryT entry, void *arg, uint32_t stackSize, int32_t priority);Create a new task. Terminated task slots are recycled to avoid unbounded array growth.
Parameter Description
@@ -3036,24 +3014,24 @@ img { max-width: 100%; }
stackSize Stack size in bytes (pass 0 for TS_DEFAULT_STACK_SIZE)
priority Scheduling priority (0..10; use TS_PRIORITY_* constants)
Returns: Task ID (>= 0) on success, or a negative error code (TS_ERR_INIT, TS_ERR_PARAM, TS_ERR_NOMEM).
-tsYield
+tsYield
void tsYield(void);Yield CPU to the next eligible ready task using credit-based round-robin. This is the sole mechanism for task switching. Every task must call this (or a GUI function that calls it) periodically, or it will monopolize the CPU.
-tsPause
+tsPause
int32_t tsPause(uint32_t taskId);Pause a task, removing it from scheduling. Cannot pause the main task (ID 0). If a task pauses itself, an implicit yield occurs.
Parameter Description --------- ----------- taskId ID of the task to pause
Returns: TS_OK on success, TS_ERR_PARAM on invalid ID, TS_ERR_STATE if the task is not in a pausable state.
-tsResume
+tsResume
int32_t tsResume(uint32_t taskId);Resume a paused task. Credits are refilled so the task gets a fair share of CPU time immediately rather than waiting for the next scheduling round.
Parameter Description --------- ----------- taskId ID of the task to resume
Returns: TS_OK on success, TS_ERR_PARAM on invalid ID, TS_ERR_STATE if the task is not paused.
-tsSetPriority
+tsSetPriority
int32_t tsSetPriority(uint32_t taskId, int32_t priority);Set a task's scheduling priority. Also refills credits so the change takes effect immediately.
Parameter Description
@@ -3061,73 +3039,72 @@ img { max-width: 100%; }
taskId ID of the task to modify
priority New priority level (0..10)
Returns: TS_OK on success, TS_ERR_PARAM on invalid ID or out-of-range priority.
-tsGetPriority
+tsGetPriority
int32_t tsGetPriority(uint32_t taskId);Get a task's current scheduling priority.
Parameter Description --------- ----------- taskId ID of the task to query
Returns: Priority value (0..10) on success, TS_ERR_PARAM on invalid ID.
-tsGetState
+tsGetState
TaskStateE tsGetState(uint32_t taskId);Get a task's current scheduling state.
Parameter Description --------- ----------- taskId ID of the task to query
Returns: TaskStateE value. Returns TaskStateTerminated for invalid IDs.
-tsCurrentId
+tsCurrentId
uint32_t tsCurrentId(void);Get the ID of the currently executing task. Always valid while the task system is initialized.
Returns: Current task ID.
-tsGetName
+tsGetName
const char *tsGetName(uint32_t taskId);Get a task's name string.
Parameter Description --------- ----------- taskId ID of the task to query
Returns: Pointer to the task's name, or NULL on invalid ID. The pointer remains valid until the task slot is reused.
-tsExit
+tsExit
void tsExit(void);Terminate the calling task. Must not be called from the main task (ID 0). The stack is freed immediately and the slot is marked for reuse. This function never returns; it performs an internal context switch to the next ready task.
-tsKill
+tsKill
int32_t tsKill(uint32_t taskId);Forcibly terminate another task. Cannot kill the main task (ID 0) or the currently running task (use tsExit() for self-termination). Safe because cooperative scheduling guarantees the target is suspended at a yield point.
Parameter Description --------- ----------- taskId ID of the task to terminate
Returns: TS_OK on success, TS_ERR_PARAM on invalid ID or illegal target (main task, self).
-tsRecoverToMain
+tsRecoverToMain
void tsRecoverToMain(void);Crash recovery: force the scheduler back to the main task (ID 0). Call after longjmp from a signal handler that fired in a non-main task. The crashed task is NOT cleaned up by this call; call tsKill() afterward to free its resources. This exists because longjmp unwinds the crashed task's stack but the scheduler state still points to it.
-tsActiveCount
+tsActiveCount
uint32_t tsActiveCount(void);Get the number of non-terminated tasks currently in the system.
Returns: Count of tasks in Ready, Running, or Paused state.
DVX Shell Library
-DVX Shell Library
The DVX shell library manages the lifecycle of DXE applications: loading, launching, tracking, and reaping. It provides the bridge between the DVX GUI compositor and dynamically loaded DXE3 application modules.
Header: shell/shellApp.h
-App Model
+App Model
The shell supports two kinds of DXE apps:
- Callback-only (hasMainLoop = false) -- appMain() runs in the shell's task 0, creates windows, registers event callbacks, and returns immediately. The app lives through GUI callbacks. Lifecycle ends when the last window is closed. Simpler and cheaper (no extra stack/task).
Main-loop (hasMainLoop = true) -- A dedicated cooperative task is created. appMain() runs in that task and can do its own polling loop, calling tsYield() to share CPU. Lifecycle ends when appMain() returns or the task is killed. Needed for terminal emulators, games, or long computations.
Both types use the same DXE interface: an exported appDescriptor and appMain function.
-DXE Interface
+DXE Interface
Every .app DXE module must export these symbols (COFF convention uses leading underscore):
Symbol Type Required ------ ---- -------- _appDescriptor AppDescriptorT Yes _appMain int32_t (*)(DxeAppContextT *) Yes _appShutdown void (*)(void) No-
State Machine
+State Machine
App slots progress through four states:
Free -> Loaded -> Running -> Terminating -> FreeLoadedE is transient (only during shellLoadApp before the entry point is called). TerminatingE means the app's task has exited but cleanup has not yet occurred. The shell's main loop reaps terminating apps each frame via shellReapApps().
-Contents
+Contents
@@ -3136,15 +3113,14 @@ img { max-width: 100%; }Shell Types and Constants
-Types and Constants
-Constants
+Types and Constants
+Constants
Constant Value Description -------- ----- ----------- SHELL_APP_NAME_MAX 64 Maximum length of an app name string. SHELL_STACK_DEFAULT 0 Use in AppDescriptorT.stackSize to get the default task stack size. SHELL_DESKTOP_APP "apps/kpunch/progman/progman.app" Default desktop application path.-
AppDescriptorT
+AppDescriptorT
Exported by every DXE app as a global named appDescriptor. The shell reads it at load time to determine how to launch the app.
Field Type Description
----- ---- -----------
@@ -3153,7 +3129,7 @@ img { max-width: 100%; }
multiInstance bool true = allow multiple simultaneous instances via temp copy.
stackSize int32_t SHELL_STACK_DEFAULT or explicit byte count for the task stack.
priority int32_t TS_PRIORITY_* value or custom priority for the task.
-DxeAppContextT
+DxeAppContextT
Passed as the sole argument to appMain(). Gives the app access to the shell's GUI context and its own identity.
Field Type Description
----- ---- -----------
@@ -3166,14 +3142,14 @@ img { max-width: 100%; }
helpFile[DVX_MAX_PATH] char[] Help file path (for F1 context help).
helpTopic[128] char[] Current help topic ID (updated by the app at runtime).
The appDir field is derived from the .app file path at load time so apps can find their own resources via relative paths. This is necessary because the working directory is shared by all apps in DOS.
-AppStateE
+AppStateE
Value Description ----- ----------- AppStateFreeE Slot is available for reuse. AppStateLoadedE DXE loaded, entry point not yet called (transient). AppStateRunningE Entry point called, app is active. AppStateTerminatingE Shutdown in progress, awaiting reap.-
ShellAppT
+ShellAppT
Per-app slot in the shell's app table. Slot 0 is reserved for the shell itself; apps use slots 1 and above.
Field Type Description
----- ---- -----------
@@ -3191,55 +3167,52 @@ img { max-width: 100%; }
App Lifecycle API
-App Lifecycle API
-shellAppInit
+shellAppInit
void shellAppInit(void);Initialize the app slot table. Seeds slot 0 (reserved for the shell). Must be called once at startup before any other shell API function.
-shellLoadApp
+shellLoadApp
int32_t shellLoadApp(AppContextT *ctx, const char *path);Load and start an app from a DXE file. Returns the app ID (>= 1) on success, or -1 on error.
For callback-only apps, appMain() runs synchronously and returns before shellLoadApp returns. For main-loop apps, a cooperative task is created and the app begins running on the next tsYield().
If multiInstance is false in the app's descriptor and the same DXE is already loaded, the call fails with an error dialog. If multiInstance is true, the DXE is copied to a temp file so dlopen gets an independent code and data image.
-shellLoadAppWithArgs
+shellLoadAppWithArgs
int32_t shellLoadAppWithArgs(AppContextT *ctx, const char *path, const char *args);Load and run an app with arguments. The args string is copied into DxeAppContextT.args before appMain() is called. Otherwise identical to shellLoadApp().
-shellReapApps
+shellReapApps
bool shellReapApps(AppContextT *ctx);Scan for and reap finished apps. Call once per frame from the main loop.
Returns true if any apps were reaped, so the caller can trigger a desktop refresh. For main-loop apps, termination is detected by the AppStateTerminatingE state (set when appMain returns). For callback-only apps, termination is detected when no windows remain for that app.
-shellReapApp
+shellReapApp
void shellReapApp(AppContextT *ctx, ShellAppT *app);Gracefully shut down a single app. Calls the app's shutdownFn (if present), destroys all windows belonging to the app, kills its task (if any), closes the DXE handle, and frees the context. The slot returns to AppStateFreeE.
-shellForceKillApp
+shellForceKillApp
void shellForceKillApp(AppContextT *ctx, ShellAppT *app);Forcibly kill an app without calling its shutdown hook. Used by the Task Manager "End Task" or when an app has crashed and cannot be trusted to run cleanup code.
Cleanup order: windows first (removes from compositor), then task (frees stack), then DXE handle (unmaps code). Closing the DXE before destroying windows would cause callbacks into unmapped code.
-shellTerminateAllApps
+shellTerminateAllApps
void shellTerminateAllApps(AppContextT *ctx);Force-kill all running apps. Called during shell shutdown. Iterates all slots and calls shellForceKillApp() on each active app.
Query API
-Query API
-shellGetApp
+shellGetApp
ShellAppT *shellGetApp(int32_t appId);Look up an app slot by ID. Returns a pointer to the ShellAppT, or NULL if the ID is out of range or the slot is free. Valid app IDs are 1 through shellAppSlotCount() - 1.
-shellAppSlotCount
+shellAppSlotCount
int32_t shellAppSlotCount(void);Return the total number of app slots (including slot 0). Use as the iteration bound when scanning all slots. Slot 0 is the shell itself; app slots start at 1.
-shellRunningAppCount
+shellRunningAppCount
int32_t shellRunningAppCount(void);Count running apps, not counting the shell itself. Includes apps in both AppStateLoadedE and AppStateRunningE states.
Configuration API
-Configuration API
Each app has a per-app configuration directory derived from its DXE path, mirrored under CONFIG/. For example, an app at APPS/KPUNCH/DVXBASIC/dvxbasic.app gets the config directory CONFIG/APPS/KPUNCH/DVXBASIC/.
-shellEnsureConfigDir
+shellEnsureConfigDir
int32_t shellEnsureConfigDir(const DxeAppContextT *ctx);Ensure the app's config directory exists, creating all parent directories as needed. Returns 0 on success, -1 on failure.
Call this before writing any config files. The directory path comes from ctx->configDir.
-shellConfigPath
+shellConfigPath
void shellConfigPath(const DxeAppContextT *ctx, const char *filename, char *outPath, int32_t outSize);Build a full path to a file in the app's config directory by joining ctx->configDir with the given filename.
// Example:
@@ -3249,44 +3222,41 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path));
Desktop Callbacks
-Desktop Callbacks
The shell provides a notification mechanism for app state changes (load, reap, crash). Desktop managers register a callback to refresh their display when apps come and go.
-shellRegisterDesktopUpdate
+shellRegisterDesktopUpdate
void shellRegisterDesktopUpdate(void (*updateFn)(void));Register a callback for app state change notifications. Multiple callbacks are supported. Apps typically call this during appMain() to receive notifications.
-shellUnregisterDesktopUpdate
+shellUnregisterDesktopUpdate
void shellUnregisterDesktopUpdate(void (*updateFn)(void));Remove a previously registered callback. Call this before app shutdown to avoid dangling function pointers.
-shellDesktopUpdate
+shellDesktopUpdate
void shellDesktopUpdate(void);Notify all registered desktop callbacks that app state has changed. Called internally by the shell after loading or reaping an app. Can also be called by apps that need to trigger a desktop refresh.
-shellCtrlEscFn
+shellCtrlEscFn
extern void (*shellCtrlEscFn)(AppContextT *ctx);Function pointer set by the taskmgr DXE's constructor. The shell calls this when Ctrl+Esc is pressed. NULL if the task manager is not loaded.
System Information
-System Information
Header: shell/shellInfo.h
Thin wrapper around the platform layer's hardware detection. Gathers system information at startup, logs it, and caches the result for display in dialogs.
-shellInfoInit
+shellInfoInit
void shellInfoInit(AppContextT *ctx);Gather all hardware information via the platform layer, log each line to DVX.LOG, and store the result for later retrieval. Call once after dvxInit().
-shellGetSystemInfo
+shellGetSystemInfo
const char *shellGetSystemInfo(void);Return the formatted system information text. The returned pointer is valid for the lifetime of the process (static buffer in the platform layer).
dvxSql -- SQL Database Interface
-dvxSql -- SQL Database Interface
+dvxSql -- SQL Database Interface
High-level wrapper around SQLite3 for DVX applications. Manages database connections and result set cursors via integer handles so BASIC code never touches raw pointers. All handles are 1-based; 0 indicates an error or invalid handle.
Header: sql/dvxSql.h
-Limits
+Limits
Constant Value Description -------- ----- ----------- MAX_DBS 16 Maximum number of simultaneously open databases. MAX_CURSORS 64 Maximum number of simultaneously open result set cursors.-
Handle Model
+Handle Model
Database and cursor handles are int32_t values. A successful open or query returns a handle greater than zero. Handle 0 is reserved as the invalid/error sentinel. Closing a database automatically finalizes all cursors that belong to it.
@@ -3294,23 +3264,22 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path));Database Operations
-Database Operations
-dvxSqlOpen
+Database Operations
+dvxSqlOpen
int32_t dvxSqlOpen(const char *path);Open a SQLite database file. Creates the file if it does not exist.
Parameter Description --------- ----------- path Path to the database file.
Returns a database handle greater than 0 on success, or 0 on error (null path, open failure, or no free slots).
-dvxSqlClose
+dvxSqlClose
void dvxSqlClose(int32_t db);Close a database and free all associated resources. Any open cursors belonging to this database are automatically finalized.
Parameter Description --------- ----------- db Database handle returned by dvxSqlOpen.
Safe to call with an invalid handle (no-op).
-dvxSqlExec
+dvxSqlExec
bool dvxSqlExec(int32_t db, const char *sql);Execute one or more SQL statements that return no result rows. Suitable for DDL (CREATE TABLE, DROP TABLE, etc.) and DML (INSERT, UPDATE, DELETE).
Parameter Description @@ -3318,14 +3287,14 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path)); db Database handle. sql SQL statement(s) to execute.
Returns true on success, false on error. On failure, the error message is available via dvxSqlError. On success, the affected row count is available via dvxSqlAffectedRows.
-dvxSqlError
+dvxSqlError
const char *dvxSqlError(int32_t db);Return the last error message for a database handle. The returned string is stored internally and valid until the next operation on the same handle.
Parameter Description --------- ----------- db Database handle.
Returns the error string, or "Invalid database handle" if the handle is invalid.
-dvxSqlAffectedRows
+dvxSqlAffectedRows
int32_t dvxSqlAffectedRows(int32_t db);Return the number of rows inserted, updated, or deleted by the last dvxSqlExec call on this handle.
Parameter Description @@ -3334,10 +3303,9 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path));Returns the row count, or 0 if the handle is invalid.
Cursor Operations
-Cursor Operations
+Cursor Operations
Result set cursors are created by dvxSqlQuery and must be freed with dvxSqlFreeResult when no longer needed. A new cursor is positioned before the first row; call dvxSqlNext to advance to the first row before reading field values.
-dvxSqlQuery
+dvxSqlQuery
int32_t dvxSqlQuery(int32_t db, const char *sql);Execute a SELECT query and return a cursor handle for iterating the results. The cursor is positioned before the first row.
Parameter Description @@ -3345,28 +3313,28 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path)); db Database handle. sql SQL SELECT statement.
Returns a cursor handle greater than 0 on success, or 0 on error (invalid handle, null SQL, SQL syntax error, or no free cursor slots). On failure, the error message is available via dvxSqlError on the database handle.
-dvxSqlNext
+dvxSqlNext
bool dvxSqlNext(int32_t rs);Advance the cursor to the next row.
Parameter Description --------- ----------- rs Cursor handle returned by dvxSqlQuery.
Returns true if a row is now available for reading, false if the cursor has reached the end or the handle is invalid.
-dvxSqlEof
+dvxSqlEof
bool dvxSqlEof(int32_t rs);Test whether the cursor is past the last row.
Parameter Description --------- ----------- rs Cursor handle.
Returns true if the cursor is exhausted or the handle is invalid, false otherwise.
-dvxSqlFieldCount
+dvxSqlFieldCount
int32_t dvxSqlFieldCount(int32_t rs);Return the number of columns in the result set.
Parameter Description --------- ----------- rs Cursor handle.
Returns the column count, or 0 if the handle is invalid.
-dvxSqlFieldName
+dvxSqlFieldName
const char *dvxSqlFieldName(int32_t rs, int32_t col);Return the name of a column by index.
Parameter Description @@ -3374,7 +3342,7 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path)); rs Cursor handle. col Column index (0-based).
Returns the column name, or "" if the handle or index is invalid.
-dvxSqlFieldText
+dvxSqlFieldText
const char *dvxSqlFieldText(int32_t rs, int32_t col);Return the value of a column as a string.
Parameter Description @@ -3382,7 +3350,7 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path)); rs Cursor handle. col Column index (0-based).
Returns the text value, or "" if the handle or index is invalid or the value is NULL.
-dvxSqlFieldByName
+dvxSqlFieldByName
const char *dvxSqlFieldByName(int32_t rs, const char *name);Return the value of a column identified by name as a string. The name match is case-insensitive.
Parameter Description @@ -3390,7 +3358,7 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path)); rs Cursor handle. name Column name (case-insensitive).
Returns the text value, or "" if the handle is invalid, the name is NULL, or no column with that name exists.
-dvxSqlFieldInt
+dvxSqlFieldInt
int32_t dvxSqlFieldInt(int32_t rs, int32_t col);Return the value of a column as a 32-bit integer.
Parameter Description @@ -3398,7 +3366,7 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path)); rs Cursor handle. col Column index (0-based).
Returns the integer value, or 0 if the handle or index is invalid.
-dvxSqlFieldDbl
+dvxSqlFieldDbl
double dvxSqlFieldDbl(int32_t rs, int32_t col);Return the value of a column as a double-precision floating point number.
Parameter Description @@ -3406,7 +3374,7 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path)); rs Cursor handle. col Column index (0-based).
Returns the double value, or 0.0 if the handle or index is invalid.
-dvxSqlFreeResult
+dvxSqlFreeResult
void dvxSqlFreeResult(int32_t rs);Close a result set cursor and free its resources. Must be called for every cursor returned by dvxSqlQuery.
Parameter Description @@ -3415,9 +3383,8 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path));Safe to call with an invalid handle (no-op).
Utility Functions
-Utility Functions
-dvxSqlEscape
+Utility Functions
+dvxSqlEscape
int32_t dvxSqlEscape(const char *src, char *dst, int32_t dstSize);Escape a string for safe inclusion in SQL string literals. Doubles single quotes so that O'Brien becomes O''Brien.
Parameter Description @@ -3428,9 +3395,8 @@ shellConfigPath(ctx, "settings.ini", path, sizeof(path));Returns the length of the escaped string (not including the null terminator), or -1 if the buffer was too small or any parameter is NULL/invalid.
Example Usage
-Example Usage
-Creating a Table and Inserting Data
+Example Usage
+Creating a Table and Inserting Data
int32_t db = dvxSqlOpen("mydata.db");
if (!db) {
// handle error
@@ -3443,7 +3409,7 @@ dvxSqlExec(db, "CREATE TABLE IF NOT EXISTS contacts ("
dvxSqlExec(db, "INSERT INTO contacts (name, phone) "
"VALUES ('Alice', '555-0100')");Querying and Iterating Results
+Querying and Iterating Results
int32_t rs = dvxSqlQuery(db, "SELECT id, name, phone FROM contacts");
if (!rs) {
printf("Error: %s\n", dvxSqlError(db));
@@ -3458,7 +3424,7 @@ while (dvxSqlNext(rs)) {
dvxSqlFreeResult(rs);
dvxSqlClose(db);Escaping User Input
+Escaping User Input
char escaped[512];
dvxSqlEscape(userInput, escaped, sizeof(escaped));
@@ -3469,24 +3435,21 @@ dvxSqlExec(db, sql);Text Help Library
-Text Help Library
Shared text editing infrastructure library for DVX widget DXEs. Provides cursor blink management, cross-widget selection clearing, word boundary logic, and a complete single-line text editing engine. Used by TextInput, Spinner, ComboBox, AnsiTerm, and other widgets that need text editing behavior.
Header: texthelp/textHelp.h
-Constants
+Constants
Constant Value Description -------- ----- ----------- TEXT_INPUT_PAD 3 Pixel padding inside text editing fields.
wgtUpdateCursorBlink
-wgtUpdateCursorBlink
+wgtUpdateCursorBlink
Advances the cursor blink timer. When the blink interval (250 ms) elapses, toggles the global sCursorBlinkOn flag and invalidates the currently focused widget for repaint. Registered automatically at library load time via a constructor function that sets the sCursorBlinkFn pointer.
void wgtUpdateCursorBlink(void);Takes no arguments and returns nothing. Called by the core event loop.
clearOtherSelections
-clearOtherSelections
+clearOtherSelections
Clears the text selection on whichever widget previously had one, unless that widget is the one passed as the argument. Tracks the last selected widget in a static pointer for O(1) lookup instead of walking the widget tree. Validates that the previous widget's window is still in the window stack before touching it, so stale pointers from closed windows are handled safely. If the previous selection was in a different window, that window gets a full repaint to clear the stale highlight.
void clearOtherSelections(WidgetT *except);Parameter Type Description @@ -3494,8 +3457,7 @@ dvxSqlExec(db, sql);except WidgetT * The widget that now owns the selection. Its selection is preserved.
isWordChar
-isWordChar
+isWordChar
Returns true if the character is alphanumeric or underscore. Used by word boundary functions to define what constitutes a "word" for double-click selection and Ctrl+arrow navigation.
bool isWordChar(char c);Parameter Type Description @@ -3504,8 +3466,7 @@ dvxSqlExec(db, sql);
Returns true if c is alphanumeric (a-z, A-Z, 0-9) or underscore.
wordEnd
-wordEnd
+wordEnd
Scans forward from the given position, returning the index of the first non-word character. Used to find the right boundary of a word for double-click word selection.
int32_t wordEnd(const char *buf, int32_t len, int32_t pos);Parameter Type Description @@ -3516,8 +3477,7 @@ dvxSqlExec(db, sql);
Returns the index one past the last word character.
wordStart
-wordStart
+wordStart
Scans backward from the given position, returning the index of the first character of the current word. Used to find the left boundary of a word for double-click word selection.
int32_t wordStart(const char *buf, int32_t pos);Parameter Type Description @@ -3527,8 +3487,7 @@ dvxSqlExec(db, sql);
Returns the index of the first character of the word containing pos.
widgetTextEditDragUpdateLine
-widgetTextEditDragUpdateLine
+widgetTextEditDragUpdateLine
Called during mouse drag to extend the selection in a single-line text field. Converts a viewport-relative pixel x coordinate to a character position and updates the cursor and selection end accordingly. Auto-scrolls the text when the mouse moves past the left or right visible edge.
void widgetTextEditDragUpdateLine(
int32_t vx, int32_t leftEdge, int32_t maxChars,
@@ -3547,8 +3506,7 @@ dvxSqlExec(db, sql);widgetTextEditMouseClick
-widgetTextEditMouseClick
+widgetTextEditMouseClick
Handles mouse click events for single-line text widgets. Converts pixel coordinates to a character position using the font's character width. Detects multi-click sequences via the core multiClickDetect() function:
- Single click -- places the cursor and begins a potential drag selection. @@ -3579,8 +3537,7 @@ dvxSqlExec(db, sql); dragSelect bool If true, single-click begins drag selection.
widgetTextEditOnKey
-widgetTextEditOnKey
+widgetTextEditOnKey
The core single-line text editing engine. Processes a single keystroke and updates the buffer, cursor, scroll offset, selection, and undo state. All state is passed by pointer so the function is reusable across TextInput, Spinner, ComboBox, and any other single-line widget.
void widgetTextEditOnKey(
WidgetT *w, int32_t key, int32_t mod,
@@ -3606,7 +3563,7 @@ dvxSqlExec(db, sql);Supported Keys
+Supported Keys
Key Action --- ------ Printable Insert character at cursor (replaces selection if active). @@ -3626,8 +3583,7 @@ dvxSqlExec(db, sql);
Fires w->onChange after any mutation (insert, delete, paste, cut, undo). Automatically adjusts scroll offset to keep cursor visible after every operation.
widgetTextEditPaintLine
-widgetTextEditPaintLine
+widgetTextEditPaintLine
Renders a single line of text with optional selection highlighting and a blinking cursor. Splits the visible text into up to three segments (pre-selection, selection, post-selection) and draws each with appropriate colors. The selection highlight uses the menu highlight colors from the color scheme. The cursor is drawn as a one-pixel vertical line when sCursorBlinkOn is true.
void widgetTextEditPaintLine(
DisplayT *d, const BlitOpsT *ops,
@@ -3662,15 +3618,14 @@ dvxSqlExec(db, sql);List Helper Library
-List Helper Library
Shared helper routines for dropdown and list-based widget DXEs (ListBox, Dropdown, ComboBox, ListView, TreeView). Provides dropdown arrow rendering, item measurement, keyboard navigation, popup geometry calculation, and popup list painting.
Header: listhelp/listHelp.h
-Constants
+Constants
Constant Value Description -------- ----- ----------- DROPDOWN_BTN_WIDTH 16 Width of the dropdown arrow button in pixels. DROPDOWN_MAX_VISIBLE 8 Maximum number of items visible in a popup list.-
widgetDrawDropdownArrow
+widgetDrawDropdownArrow
Draw the triangular dropdown arrow glyph centered at a given position.
void widgetDrawDropdownArrow(DisplayT *d, const BlitOpsT *ops,
int32_t centerX, int32_t centerY, uint32_t color);widgetMaxItemLen
+widgetMaxItemLen
Scan an array of strings and return the length (in characters) of the longest item.
int32_t widgetMaxItemLen(const char **items, int32_t count);Parameter Description @@ -3689,7 +3644,7 @@ dvxSqlExec(db, sql);items Array of null-terminated string pointers. count Number of items in the array.
Returns the character length of the longest item, or 0 if count is zero.
-widgetNavigateIndex
+widgetNavigateIndex
Compute a new selected index from a navigation key press. Handles Up, Down, Home, End, Page Up, and Page Down.
int32_t widgetNavigateIndex(int32_t key, int32_t current,
int32_t count, int32_t pageSize);Returns the new index, clamped to [0, count-1].
-widgetDropdownPopupRect
+widgetDropdownPopupRect
Calculate the screen rectangle for a dropdown popup list, positioning it below the owning widget and clamping to screen bounds.
void widgetDropdownPopupRect(WidgetT *w, const BitmapFontT *font,
int32_t contentH, int32_t itemCount,
@@ -3716,7 +3671,7 @@ dvxSqlExec(db, sql);The popup is sized to show up to DROPDOWN_MAX_VISIBLE items.
-widgetPaintPopupList
+widgetPaintPopupList
Render a popup item list with highlight, scrolling, and beveled border.
void widgetPaintPopupList(DisplayT *d, const BlitOpsT *ops,
const BitmapFontT *font, const ColorSchemeT *colors,
@@ -3740,25 +3695,23 @@ dvxSqlExec(db, sql);Task Manager
-Task Manager
System-level task manager for DVX. Displays running applications and per-app memory usage. Always accessible via Ctrl+Esc regardless of which application is focused. Persists independently of the desktop app (Program Manager).
Header: taskmgr/shellTaskMgr.h
Loaded as: bin/libs/taskmgr.lib
-shellTaskMgrOpen
+shellTaskMgrOpen
Open the Task Manager window, or raise it to the front if already open.
void shellTaskMgrOpen(AppContextT *ctx);Parameter Description --------- ----------- ctx Application context (from dvxInit). Required for window creation and event registration.
Called by the shell's global Ctrl+Esc handler.
-shellTaskMgrRefresh
+shellTaskMgrRefresh
Refresh the task list display. Call this when applications are launched or terminated so the Task Manager reflects the current state.
void shellTaskMgrRefresh(void);Takes no parameters. Safe to call even if the Task Manager window is not currently open (the call is a no-op in that case).
Serial Stack
-Serial Stack
The DVX serial/networking stack provides reliable, optionally encrypted communication over RS-232 serial ports. It is composed of four layers, each building on the one below:
- rs232 -- ISR-driven UART driver with ring buffers and flow control @@ -3774,24 +3727,23 @@ dvxSqlExec(db, sql);
RS-232 UART Driver
-RS-232 UART Driver
ISR-driven serial port driver supporting up to 4 simultaneous COM ports. A shared ISR drains UART FIFOs into per-port ring buffers (2048 bytes, power-of-2 for fast index wrapping). Flow control (XON/XOFF, RTS/CTS, DTR/DSR) operates within the ISR using watermark thresholds. All ISR data structures are DPMI-locked to prevent page faults.
Header: rs232/rs232.h
-Port Constants
+Port Constants
Constant Value Description -------- ----- ----------- RS232_COM1 0 First serial port. RS232_COM2 1 Second serial port. RS232_COM3 2 Third serial port. RS232_COM4 3 Fourth serial port.-
Handshake Modes
+Handshake Modes
Constant Value Description -------- ----- ----------- RS232_HANDSHAKE_NONE 0 No flow control. RS232_HANDSHAKE_XONXOFF 1 Software flow control (XON/XOFF characters). RS232_HANDSHAKE_RTSCTS 2 Hardware flow control via RTS/CTS lines. RS232_HANDSHAKE_DTRDSR 3 Hardware flow control via DTR/DSR lines.-
UART Types
+UART Types
Detected automatically by probing the scratch register and FIFO capability.
Constant Value Description -------- ----- ----------- @@ -3800,7 +3752,7 @@ dvxSqlExec(db, sql);RS232_UART_16450 2 Has scratch register, no FIFO. RS232_UART_16550 3 Has FIFO but buggy (rare). RS232_UART_16550A 4 Working 16-byte FIFO. Most common in 486+ hardware. -
Error Codes
+Error Codes
Constant Value Description -------- ----- ----------- RS232_SUCCESS 0 Operation succeeded. @@ -3820,7 +3772,7 @@ dvxSqlExec(db, sql);RS232_ERR_NULL_PTR -14 NULL pointer argument. RS232_ERR_IRQ_NOT_FOUND -15 Could not detect IRQ for port. RS232_ERR_LOCK_MEM -16 DPMI memory lock failed. -
rs232Open
+rs232Open
Open a COM port with the specified line parameters.
int rs232Open(int com, int32_t bps, int dataBits,
char parity, int stopBits, int handshake);Returns RS232_SUCCESS or a negative error code.
-rs232Close
+rs232Close
Close a COM port and release its ISR resources.
int rs232Close(int com);rs232Read
+rs232Read
Non-blocking read from the receive ring buffer.
int rs232Read(int com, char *data, int len);Parameter Description @@ -3845,19 +3797,19 @@ dvxSqlExec(db, sql);data Buffer to receive data. len Maximum bytes to read.
Returns the number of bytes actually read (may be less than len).
-rs232Write
+rs232Write
Blocking polled write directly to UART transmit holding register. Bypasses the TX ring buffer. Use for small, immediate writes.
int rs232Write(int com, const char *data, int len);Returns RS232_SUCCESS or a negative error code.
-rs232WriteBuf
+rs232WriteBuf
Non-blocking write to the transmit ring buffer. The ISR drains buffered data to the UART asynchronously.
int rs232WriteBuf(int com, const char *data, int len);Returns the number of bytes actually queued (may be less than len if the buffer is full).
-rs232Set
+rs232Set
Change all line parameters on an open port.
int rs232Set(int com, int32_t bps, int dataBits,
char parity, int stopBits, int handshake);Configuration Getters
+Configuration Getters
Function Returns -------- ------- rs232GetBase(com) I/O base address. @@ -3868,7 +3820,7 @@ dvxSqlExec(db, sql);rs232GetHandshake(com) Handshake mode. rs232GetIrq(com) IRQ number. rs232GetUartType(com) Detected UART type (RS232_UART_*). -
Status Getters
+Status Getters
Function Returns -------- ------- rs232GetRxBuffered(com) Bytes waiting in the receive ring buffer. @@ -3880,7 +3832,7 @@ dvxSqlExec(db, sql);rs232GetLsr(com) Line status register value. rs232GetMcr(com) Modem control register value. rs232GetMsr(com) Modem status register value. -
Configuration Setters
+Configuration Setters
Function Description -------- ----------- rs232SetBase(com, base) Set I/O base address (before open). @@ -3894,7 +3846,7 @@ dvxSqlExec(db, sql);rs232SetDtr(com, dtr) Set DTR line state. rs232SetRts(com, rts) Set RTS line state. rs232SetFifoThreshold(com, thr) Set FIFO trigger level (1, 4, 8, or 14 bytes). -
Buffer Management
+Buffer Management
Function Description -------- ----------- rs232ClearRxBuffer(com) Discard all data in the receive ring buffer. @@ -3902,16 +3854,15 @@ dvxSqlExec(db, sql);
Packet Transport
-Packet Transport
Reliable, ordered packet delivery over an RS-232 serial link. Uses HDLC-style byte-stuffed framing for frame delimiting, CRC-16-CCITT for error detection, and Go-Back-N ARQ with a configurable sliding window for retransmission.
Header: packet/packet.h
-Constants
+Constants
Constant Value Description -------- ----- ----------- PKT_MAX_PAYLOAD 255 Maximum bytes per packet payload. PKT_DEFAULT_WINDOW 4 Default sliding window size (unacknowledged frames in flight). PKT_MAX_WINDOW 8 Maximum sliding window size.-
Error Codes
+Error Codes
Constant Value Description -------- ----- ----------- PKT_SUCCESS 0 Operation succeeded. @@ -3924,7 +3875,7 @@ dvxSqlExec(db, sql);PKT_ERR_TX_FULL -7 Transmit window is full. PKT_ERR_NO_DATA -8 No data available. PKT_ERR_DISCONNECTED -9 Remote side disconnected. -
PktRecvCallbackT
+PktRecvCallbackT
Callback type for received packets.
typedef void (*PktRecvCallbackT)(void *ctx,
const uint8_t *data, int len);pktOpen
+pktOpen
Open a packetized connection over an already-open COM port.
PktConnT *pktOpen(int com, int windowSize,
PktRecvCallbackT callback, void *callbackCtx);Returns an opaque PktConnT handle, or NULL on failure.
-pktClose
+pktClose
Close a packetized connection. Does not close the underlying COM port.
void pktClose(PktConnT *conn);pktSend
+pktSend
Send a data packet.
int pktSend(PktConnT *conn, const uint8_t *data,
int len, bool block);Returns PKT_SUCCESS or a negative error code.
-pktPoll
+pktPoll
Poll for incoming data, process received frames, and handle retransmits. Must be called frequently in the main loop.
int pktPoll(PktConnT *conn);Returns the number of valid data packets delivered to the callback.
-pktReset
+pktReset
Reset the connection state (sequence numbers, buffers) and send a RST frame to the remote side.
int pktReset(PktConnT *conn);pktCanSend
+pktCanSend
Check whether there is room in the transmit window for another packet.
bool pktCanSend(PktConnT *conn);pktGetPending
+pktGetPending
Get the number of unacknowledged packets currently in the transmit window.
int pktGetPending(PktConnT *conn);Security (DH + XTEA)
-Security (DH + XTEA)
Cryptographic primitives for the serial stack: 1024-bit Diffie-Hellman key exchange (RFC 2409 Group 2), XTEA block cipher in CTR mode, and an XTEA-CTR DRBG random number generator.
XTEA requires no lookup tables and compiles to approximately 20 instructions per round, making it suitable for 486-class hardware where AES S-box tables would thrash the 8KB cache.
Header: security/security.h
-Constants
+Constants
Constant Value Description -------- ----- ----------- SEC_DH_KEY_SIZE 128 Size of a DH public key in bytes (1024 bits). SEC_XTEA_KEY_SIZE 16 Size of an XTEA key in bytes (128 bits).-
Error Codes
+Error Codes
Constant Value Description -------- ----- ----------- SEC_SUCCESS 0 Operation succeeded. SEC_ERR_PARAM -1 Invalid parameter. SEC_ERR_NOT_READY -2 DH context not ready (keys not generated or secret not computed). SEC_ERR_ALLOC -3 Memory allocation failed.-
RNG Functions
+RNG Functions
The RNG uses XTEA-CTR as a DRBG. Hardware entropy from PIT timer jitter is weak (~20 bits); supplement with keyboard timing or mouse jitter before generating DH keys.
void secRngSeed(const uint8_t *entropy, int len);
int secRngGatherEntropy(uint8_t *buf, int len);
@@ -4002,7 +3952,7 @@ void secRngBytes(uint8_t *buf, int len);Diffie-Hellman Key Exchange
+Diffie-Hellman Key Exchange
1024-bit DH with 256-bit private exponents using the RFC 2409 Group 2 safe prime.
SecDhT *secDhCreate(void);
int secDhGenerateKeys(SecDhT *dh);
@@ -4020,7 +3970,7 @@ void secDhDestroy(SecDhT *dh);Typical usage order: secDhCreate, secDhGenerateKeys, exchange public keys, secDhComputeSecret, secDhDeriveKey, secDhDestroy.
-XTEA-CTR Cipher
+XTEA-CTR Cipher
XTEA in counter mode. Encrypt and decrypt are the same operation (XOR with keystream). The counter must never repeat with the same key.
SecCipherT *secCipherCreate(const uint8_t *key);
void secCipherSetNonce(SecCipherT *c,
@@ -4037,16 +3987,15 @@ void secCipherDestroy(SecCipherT *c);Secure Link
-Secure Link
Top-level API composing all three lower layers (rs232, packet, security) into a single interface. Provides channel multiplexing (0-127) and per-packet encryption control over a reliable serial link.
Each packet carries a one-byte header: bit 7 is the encrypted flag, bits 6..0 are the channel number. Unencrypted packets can be sent before the handshake completes (e.g., for version negotiation).
Header: seclink/secLink.h
-Constants
+Constants
Constant Value Description -------- ----- ----------- SECLINK_MAX_PAYLOAD 254 Maximum plaintext bytes per send (PKT_MAX_PAYLOAD minus 1-byte channel header). SECLINK_MAX_CHANNEL 127 Highest valid channel number.-
Error Codes
+Error Codes
Constant Value Description -------- ----- ----------- SECLINK_SUCCESS 0 Operation succeeded. @@ -4056,11 +4005,11 @@ void secCipherDestroy(SecCipherT *c);SECLINK_ERR_HANDSHAKE -4 DH handshake failed. SECLINK_ERR_NOT_READY -5 Handshake not yet completed (encrypted send attempted). SECLINK_ERR_SEND -6 Packet send failed. -
SecLinkRecvT
+SecLinkRecvT
Receive callback type. Delivers decrypted plaintext with the channel number.
typedef void (*SecLinkRecvT)(void *ctx,
const uint8_t *data, int len, uint8_t channel);secLinkOpen
+secLinkOpen
Open a secure serial link. Opens the COM port and packet layer internally.
SecLinkT *secLinkOpen(int com, int32_t bps, int dataBits,
char parity, int stopBits, int handshake,
@@ -4076,14 +4025,14 @@ void secCipherDestroy(SecCipherT *c);Returns an opaque SecLinkT handle, or NULL on failure.
-secLinkClose
+secLinkClose
Close the link, free all resources, and close the COM port.
void secLinkClose(SecLinkT *link);secLinkHandshake
+secLinkHandshake
Perform Diffie-Hellman key exchange. Blocks until both sides complete. The RNG must be seeded before calling this.
int secLinkHandshake(SecLinkT *link);Returns SECLINK_SUCCESS or SECLINK_ERR_HANDSHAKE.
-secLinkSend
+secLinkSend
Send data on a channel, optionally encrypted.
int secLinkSend(SecLinkT *link, const uint8_t *data,
int len, uint8_t channel, bool encrypt, bool block);Returns SECLINK_SUCCESS or a negative error code.
-secLinkSendBuf
+secLinkSendBuf
Send an arbitrarily large buffer by splitting into SECLINK_MAX_PAYLOAD chunks. Always blocks until all data is sent.
int secLinkSendBuf(SecLinkT *link, const uint8_t *data,
int len, uint8_t channel, bool encrypt);Returns SECLINK_SUCCESS or the first error encountered.
-secLinkPoll
+secLinkPoll
Poll for incoming data. Decrypts encrypted packets and delivers plaintext to the receive callback.
int secLinkPoll(SecLinkT *link);Returns the number of packets delivered, or a negative error code.
-secLinkIsReady
+secLinkIsReady
Check whether the handshake is complete and the link is ready for encrypted data.
bool secLinkIsReady(SecLinkT *link);secLinkGetPending
+secLinkGetPending
Get the number of unacknowledged packets in the transmit window.
int secLinkGetPending(SecLinkT *link);BASIC Runtime Library
-BASIC Runtime Library
Stack-based p-code virtual machine and value system for DVX BASIC. Embeddable: the host provides I/O and UI callbacks. No DVX GUI dependencies in the core runtime.
Headers: apps/dvxbasic/runtime/vm.h, apps/dvxbasic/runtime/values.h
@@ -4122,10 +4070,9 @@ void secCipherDestroy(SecCipherT *c);Value System
-Value System
Tagged union value type for the VM evaluation stack, variables, and array elements. Strings, arrays, and UDT instances are reference-counted for automatic memory management without a garbage collector.
Header: apps/dvxbasic/runtime/values.h
-Type Tags
+Type Tags
Constant Value C Union Field Description -------- ----- ------------- ----------- BAS_TYPE_INTEGER 0 intVal 16-bit signed integer. @@ -4138,7 +4085,7 @@ void secCipherDestroy(SecCipherT *c);BAS_TYPE_UDT 7 udtVal Reference-counted user-defined type. BAS_TYPE_OBJECT 8 objVal Opaque host pointer (form, control). BAS_TYPE_REF 9 refVal ByRef pointer to a BasValueT slot. -
BasValueT
+BasValueT
Tagged union holding any BASIC value.
struct BasValueTag {
uint8_t type; // BAS_TYPE_*
@@ -4155,7 +4102,7 @@ void secCipherDestroy(SecCipherT *c);Value Constructors
+Value Constructors
BasValueT basValInteger(int16_t v);
BasValueT basValLong(int32_t v);
BasValueT basValSingle(float v);
@@ -4165,14 +4112,14 @@ BasValueT basValStringFromC(const char *text);
BasValueT basValBool(bool v);
BasValueT basValObject(void *obj);Each returns a BasValueT with the appropriate type tag set. basValString increments the string's reference count.
-Value Lifetime
+Value Lifetime
BasValueT basValCopy(BasValueT v);
void basValRelease(BasValueT *v);Function Description -------- ----------- basValCopy Copy a value. Increments reference count for strings, arrays, and UDTs. basValRelease Release a value. Decrements reference count and frees if it reaches zero.-
Type Conversion
+Type Conversion
BasValueT basValToInteger(BasValueT v);
BasValueT basValToLong(BasValueT v);
BasValueT basValToSingle(BasValueT v);
@@ -4180,7 +4127,7 @@ BasValueT basValToDouble(BasValueT v);
BasValueT basValToString(BasValueT v);
BasValueT basValToBool(BasValueT v);Each returns a new value of the target type. The original is not released; the caller manages both lifetimes.
-Value Utilities
+Value Utilities
Function Description -------- ----------- basValToNumber(v) Convert any numeric value to double. @@ -4189,7 +4136,7 @@ BasValueT basValToBool(BasValueT v);basValCompare(a, b) Compare two values. Returns -1, 0, or 1. basValCompareCI(a, b) Case-insensitive comparison (OPTION COMPARE TEXT). basValPromoteType(a, b) Determine common type for binary ops (e.g. Integer + Single -> Single). -
BasStringT
+BasStringT
Reference-counted string with flexible array member for inline storage.
typedef struct {
int32_t refCount;
@@ -4197,7 +4144,7 @@ BasValueT basValToBool(BasValueT v);String Functions
+String Functions
Function Description -------- ----------- basStringNew(text, len) Allocate from a C string. refCount starts at 1. @@ -4211,7 +4158,7 @@ BasValueT basValToBool(BasValueT v);basStringSystemInit() Initialize the string system and empty string singleton. basStringSystemShutdown() Shut down the string system.
The global basEmptyString is a singleton that is never freed.
-BasArrayT
+BasArrayT
Reference-counted multi-dimensional array (up to BAS_ARRAY_MAX_DIMS = 8 dimensions).
typedef struct {
int32_t refCount;
@@ -4222,7 +4169,7 @@ BasValueT basValToBool(BasValueT v);Array Functions
+Array Functions
Function Description -------- ----------- basArrayNew(dims, lbounds, ubounds, type) Allocate an array. refCount starts at 1. @@ -4230,7 +4177,7 @@ BasValueT basValToBool(BasValueT v);basArrayRef(arr) Increment reference count. basArrayUnref(arr) Decrement reference count. Frees at zero. basArrayIndex(arr, indices, ndims) Compute flat index from multi-dimensional indices. Returns -1 if out of bounds. -
BasUdtT
+BasUdtT
Reference-counted user-defined type instance.
typedef struct {
int32_t refCount;
@@ -4238,7 +4185,7 @@ BasValueT basValToBool(BasValueT v);UDT Functions
+UDT Functions
Function Description -------- ----------- basUdtNew(typeId, fieldCount) Allocate a UDT instance. refCount starts at 1. @@ -4248,10 +4195,9 @@ BasValueT basValToBool(BasValueT v);
Virtual Machine
-Virtual Machine
Stack-based p-code interpreter. Executes compiled BASIC bytecode modules. The host provides I/O, UI, SQL, and external library callbacks. The VM has no DVX dependencies; it can be embedded in any C program.
Header: apps/dvxbasic/runtime/vm.h
-VM Limits
+VM Limits
Constant Value Description -------- ----- ----------- BAS_VM_STACK_SIZE 256 Evaluation stack depth. @@ -4260,7 +4206,7 @@ BasValueT basValToBool(BasValueT v);BAS_VM_MAX_LOCALS 64 Local variables per stack frame. BAS_VM_MAX_FOR_DEPTH 32 Maximum nested FOR loop depth. BAS_VM_MAX_FILES 16 Open file channels (1-based). -
BasVmResultE
+BasVmResultE
Result codes returned by basVmRun and basVmStep.
Code Value Description ---- ----- ----------- @@ -4280,7 +4226,7 @@ BasValueT basValToBool(BasValueT v);BAS_VM_USER_ERROR 13 ON ERROR raised by program. BAS_VM_STEP_LIMIT 14 Step limit reached (not an error). BAS_VM_BREAKPOINT 15 Breakpoint or step completed (not an error). -
Lifecycle
+Lifecycle
BasVmT *basVmCreate(void);
void basVmDestroy(BasVmT *vm);
void basVmLoadModule(BasVmT *vm, BasModuleT *module);
@@ -4291,7 +4237,7 @@ void basVmReset(BasVmT *vm);Execution
+Execution
BasVmResultE basVmRun(BasVmT *vm);
BasVmResultE basVmStep(BasVmT *vm);
void basVmSetStepLimit(BasVmT *vm, int32_t limit);I/O Callbacks
+I/O Callbacks
The host provides these callbacks for PRINT, INPUT, and DoEvents statements.
void basVmSetPrintCallback(BasVmT *vm, BasPrintFnT fn, void *ctx);
void basVmSetInputCallback(BasVmT *vm, BasInputFnT fn, void *ctx);
void basVmSetDoEventsCallback(BasVmT *vm, BasDoEventsFnT fn, void *ctx);Callback Types
+Callback Types
typedef void (*BasPrintFnT)(void *ctx, const char *text, bool newline);
typedef bool (*BasInputFnT)(void *ctx, const char *prompt,
char *buf, int32_t bufSize);
@@ -4315,10 +4261,10 @@ typedef bool (*BasDoEventsFnT)(void *ctx);UI Callbacks
+UI Callbacks
For form and control integration. The VM resolves all UI operations through these callbacks, keeping it independent of any specific GUI toolkit.
void basVmSetUiCallbacks(BasVmT *vm, const BasUiCallbacksT *ui);BasUiCallbacksT
+BasUiCallbacksT
Field Signature Description ----- --------- ----------- getProp BasValueT (*)(ctx, ctrlRef, propName) Get a control property value. @@ -4334,10 +4280,10 @@ typedef bool (*BasDoEventsFnT)(void *ctx);msgBox int32_t (*)(ctx, message, flags) Display a message box. inputBox BasStringT *(*)(ctx, prompt, title, defaultText) Display an input box. ctx void * User pointer passed to all callbacks. -
SQL Callbacks
+SQL Callbacks
For database integration.
void basVmSetSqlCallbacks(BasVmT *vm, const BasSqlCallbacksT *sql);BasSqlCallbacksT
+BasSqlCallbacksT
Field Signature Description ----- --------- ----------- sqlOpen int32_t (*)(path) Open a database. Returns handle. @@ -4355,30 +4301,30 @@ typedef bool (*BasDoEventsFnT)(void *ctx);sqlFieldDbl double (*)(rs, col) Get column value as double. sqlFreeResult void (*)(rs) Free a result set. sqlAffectedRows int32_t (*)(db) Get number of rows affected by last statement. -
External Library Callbacks
+External Library Callbacks
For DECLARE LIBRARY support. The VM resolves external functions at runtime via the host.
void basVmSetExternCallbacks(BasVmT *vm,
const BasExternCallbacksT *ext);BasExternCallbacksT
+BasExternCallbacksT
Field Signature Description ----- --------- ----------- resolveExtern void *(*)(ctx, libName, funcName) Resolve a native function by library and symbol name. Cached after first call. callExtern BasValueT (*)(ctx, funcPtr, funcName, args, argc, retType) Call a resolved native function, marshalling arguments and return value. ctx void * User pointer passed to both callbacks.-
Form Context
+Form Context
Set the active form context during event dispatch.
void basVmSetCurrentForm(BasVmT *vm, void *formRef);
void basVmSetCurrentFormVars(BasVmT *vm,
BasValueT *vars, int32_t count);Stack Access
+Stack Access
Push and pop values on the evaluation stack for host integration.
bool basVmPush(BasVmT *vm, BasValueT val);
bool basVmPop(BasVmT *vm, BasValueT *val);Both return true on success, false on stack overflow/underflow.
-Error Reporting
+Error Reporting
const char *basVmGetError(const BasVmT *vm);Returns the current error message string. Valid after basVmRun returns BAS_VM_ERROR.
-Sub/Function Calls from Host
+Sub/Function Calls from Host
Call a SUB or FUNCTION by its code address from host code.
bool basVmCallSub(BasVmT *vm, int32_t codeAddr);
bool basVmCallSubWithArgs(BasVmT *vm, int32_t codeAddr,
@@ -4392,7 +4338,7 @@ bool basVmCallSubWithArgsOut(BasVmT *vm, int32_t codeAddr,
basVmCallSubWithArgs Call a SUB with arguments pushed onto the stack frame.
basVmCallSubWithArgsOut Call a SUB and read back modified argument values after it returns.All three push a call frame, execute until the SUB returns, then restore the previous execution state. Return true on normal completion, false on error or if the VM is not idle.
-Debugger API
+Debugger API
void basVmSetBreakpoints(BasVmT *vm,
int32_t *lines, int32_t count);
void basVmStepInto(BasVmT *vm);
@@ -4410,7 +4356,7 @@ int32_t basVmGetCurrentLine(const BasVmT *vm);The breakpoint callback notifies the host when a breakpoint fires during nested sub calls:
typedef void (*BasBreakpointFnT)(void *ctx, int32_t line);BasModuleT
+BasModuleT
Compiled module produced by the BASIC compiler and loaded into the VM.
typedef struct {
uint8_t *code;
@@ -4450,13 +4396,12 @@ int32_t basVmGetCurrentLine(const BasVmT *vm);Base WidgetT (Common Properties, Events, and Operations)
-DVX Widget System
+DVX Widget System
Complete reference for the DVX GUI widget toolkit. All widgets are implemented as dynamically loaded DXE modules. They are created via convenience macros that wrap the per-widget API function tables. The base WidgetT structure is defined in core/dvxWidget.h; individual widget headers live in widgets/.
Individual widgets are documented in their own sections. See the table of contents for the full list.
-Base WidgetT (Common Properties, Events, and Operations)
+Base WidgetT (Common Properties, Events, and Operations)
Every widget inherits from the WidgetT structure defined in core/dvxWidget.h. The fields and callbacks listed here are available on all widget types.
-Common Properties
+Common Properties
Field Type Description ----- ---- ----------- name char[32] Widget name for lookup via wgtFind(). @@ -4478,13 +4423,13 @@ int32_t basVmGetCurrentLine(const BasVmT *vm);tooltip const char * Tooltip text. NULL = none. Caller owns the string. contextMenu MenuT * Right-click context menu. NULL = none. Caller owns. userData void * Application-defined user data pointer. -
Size Specification Macros
+Size Specification Macros
Macro Description ----- ----------- wgtPixels(v) Size in pixels. wgtChars(v) Size in character widths (multiplied by font charWidth). wgtPercent(v) Size as a percentage of parent dimension.-
Common Events (Callbacks)
+Common Events (Callbacks)
These callback function pointers are available on every WidgetT. Set them directly on the widget struct.
Callback Signature Description -------- --------- ----------- @@ -4501,7 +4446,7 @@ int32_t basVmGetCurrentLine(const BasVmT *vm);onMouseMove void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse movement over the widget. onScroll void (*)(WidgetT *w, int32_t delta) Fires on mouse wheel scroll. onValidate bool (*)(WidgetT *w) Validation callback. Return false to cancel a pending write. -
Common Operations
+Common Operations
Function Description -------- ----------- WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win) Initialize widgets for a window. Returns the root VBox container. @@ -4521,13 +4466,12 @@ int32_t basVmGetCurrentLine(const BasVmT *vm);void wgtSetTooltip(WidgetT *w, const char *text) Set tooltip text. Pass NULL to remove.
AnsiTerm
-AnsiTerm
+AnsiTerm
A VT100/ANSI-compatible terminal emulator widget designed for connecting to BBS systems over the serial link. Uses a traditional text-mode cell buffer (character + attribute byte pairs) with the CP437 character set and 16-color CGA palette. Supports cursor movement, screen/line erase, scrolling regions, SGR colors, and scrollback history. Communication is abstracted through read/write function pointers, allowing the terminal to work with raw serial ports, the secLink encrypted channel, or any other byte-oriented transport.
Header: widgets/widgetAnsiTerm.h
-Creation
+Creation
WidgetT *term = wgtAnsiTerm(parent, 80, 25);Macros
+Macros
Macro Description ----- ----------- wgtAnsiTerm(parent, cols, rows) Create an ANSI terminal widget with the given column and row dimensions. @@ -4537,32 +4481,31 @@ int32_t basVmGetCurrentLine(const BasVmT *vm);wgtAnsiTermSetScrollback(w, maxLines) Set the maximum number of scrollback lines. Lines scrolled off the top are saved in a circular buffer. wgtAnsiTermPoll(w) Poll the communication channel for incoming data and feed it into the ANSI parser. wgtAnsiTermRepaint(w, outY, outH) Fast repaint path that renders dirty rows directly into the window's content buffer, bypassing the widget pipeline. Returns the dirty region via outY/outH. -
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Cols Integer Read-only Number of columns. Rows Integer Read-only Number of rows. Scrollback Integer Write-only Maximum scrollback lines.-
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- Clear Clear the terminal screen. Write Write a string into the terminal.-
Events
+Events
AnsiTerm uses the common events only. No widget-specific events are defined.
Box (VBox / HBox / Frame)
-Box (VBox / HBox / Frame)
+Box (VBox / HBox / Frame)
Container widgets that arrange their children in a vertical column (VBox), horizontal row (HBox), or a titled group box (Frame). These are the primary layout building blocks. Children are laid out using a flexbox-like algorithm with weight-based extra-space distribution.
Header: widgets/widgetBox.h
-Creation
+Creation
Macro Description ----- ----------- wgtVBox(parent) Create a vertical box container. Children are stacked top to bottom. wgtHBox(parent) Create a horizontal box container. Children are placed left to right. wgtFrame(parent, title) Create a titled group box (a VBox with a border and label).-
Properties
+Properties
Box containers use the common WidgetT fields for layout control:
Property Description -------- ----------- @@ -4570,35 +4513,33 @@ int32_t basVmGetCurrentLine(const BasVmT *vm);spacing Gap between children (tagged size). padding Internal padding around children (tagged size). weight Controls how the box itself stretches within its parent. -
Events
+Events
Containers use the common events only. No widget-specific events.
Button
-Button
+Button
A push button with a text label. Fires onClick when pressed and released. Supports keyboard activation via accelerator keys.
Header: widgets/widgetButton.h
-Creation
+Creation
WidgetT *btn = wgtButton(parent, "OK");Macro
+Macro
Macro Description ----- ----------- wgtButton(parent, text) Create a push button with the given label text.-
Properties
+Properties
Uses common WidgetT properties. Set accelKey for keyboard shortcut. Use wgtSetText() / wgtGetText() to change the label.
-Events
+Events
Callback Description -------- ----------- onClick Fires when the button is clicked (press + release).
Canvas
-Canvas
+Canvas
A freeform drawing surface with a fixed-size pixel buffer. Provides drawing primitives (lines, rectangles, circles, text, individual pixels) and supports save/load to BMP files. Mouse interaction is available via a callback.
Header: widgets/widgetCanvas.h
-Creation
+Creation
WidgetT *cv = wgtCanvas(parent, 320, 200);Macros
+Macros
Macro Description ----- ----------- wgtCanvas(parent, w, h) Create a canvas with the given pixel dimensions. @@ -4615,72 +4556,69 @@ int32_t basVmGetCurrentLine(const BasVmT *vm);wgtCanvasSetMouseCallback(w, cb) Set a mouse interaction callback. Signature: void (*cb)(WidgetT *w, int32_t cx, int32_t cy, bool drag). Receives canvas-relative coordinates and whether the mouse is being dragged. wgtCanvasSave(w, path) Save the canvas contents to a BMP file. wgtCanvasLoad(w, path) Load a BMP file into the canvas. -
Events
+Events
Callback Description -------- ----------- onClick Fires when the canvas is clicked. Mouse callback (via wgtCanvasSetMouseCallback) Fires on mouse down and drag with canvas-local coordinates.-
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- Clear Clear the canvas to a given color.
Checkbox
-Checkbox
+Checkbox
A toggle control with a text label. Clicking toggles between checked and unchecked states.
Header: widgets/widgetCheckbox.h
-Creation
+Creation
WidgetT *cb = wgtCheckbox(parent, "Enable logging");Macros
+Macros
Macro Description ----- ----------- wgtCheckbox(parent, text) Create a checkbox with the given label text. wgtCheckboxIsChecked(w) Returns true if the checkbox is checked. wgtCheckboxSetChecked(w, checked) Set the checked state programmatically.-
Events
+Events
Callback Description -------- ----------- onClick Fires when clicked (after toggle). onChange Fires when the checked state changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Value Boolean Read/Write Whether the checkbox is checked.
ComboBox
-ComboBox
+ComboBox
A combination of a text input and a dropdown list. The user can either type a value or select from a list of predefined options. Unlike Dropdown, the text field is editable.
Header: widgets/widgetComboBox.h
-Creation
+Creation
WidgetT *cb = wgtComboBox(parent, 128);
const char *items[] = { "Arial", "Courier", "Times" };
wgtComboBoxSetItems(cb, items, 3);Macros
+Macros
Macro Description ----- ----------- wgtComboBox(parent, maxLen) Create a combo box. maxLen is the maximum text input length. wgtComboBoxSetItems(w, items, count) Set the dropdown items. wgtComboBoxGetSelected(w) Get the index of the selected item (-1 if the text does not match any item). wgtComboBoxSetSelected(w, idx) Set the selected item by index.-
Events
+Events
Callback Description -------- ----------- onChange Fires when the text or selection changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- ListIndex Integer Read/Write Index of the currently selected item.
DataCtrl
-DataCtrl
+DataCtrl
A VB3-style Data control for database binding. Displays a visible navigation bar that connects to a SQLite database via dvxSql* functions. Reads all rows from the RecordSource query into an in-memory cache for bidirectional navigation. Fires Reposition events when the cursor moves so bound controls can update. Supports master-detail linking between Data controls.
Header: widgets/widgetDataCtrl.h
-Creation
+Creation
WidgetT *data = wgtDataCtrl(parent);Macros
+Macros
Macro Description ----- ----------- wgtDataCtrl(parent) Create a Data control. @@ -4701,7 +4639,7 @@ wgtComboBoxSetItems(cb, items, 3);wgtDataCtrlGetColName(w, col) Get the name of a column by index. Returns const char *. wgtDataCtrlGetCellText(w, row, col) Get the text of a specific cell by row and column index. Returns const char *. wgtDataCtrlSetCurrentRow(w, row) Set the current row by index (0-based). -
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- DatabaseName String Read/Write Path to the SQLite database file. @@ -4713,7 +4651,7 @@ wgtComboBoxSetItems(cb, items, 3);Caption String Read/Write Text displayed on the navigation bar. BOF Boolean Read-only True when the cursor is before the first row. EOF Boolean Read-only True when the cursor is past the last row. -
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- AddNew Begin a new row. @@ -4724,21 +4662,20 @@ wgtComboBoxSetItems(cb, items, 3);MovePrevious Move to the previous row. Refresh Re-execute the query and rebuild the cache. Update Write pending changes to the database. -
Events
+Events
Event Description ----- ----------- Reposition Fires when the current row changes (navigation, refresh, etc.). Default event. Validate Fires before writing changes. Return false to cancel.
DbGrid
-DbGrid
+DbGrid
A database grid widget that displays all records from a Data control in a scrollable, sortable table. Columns auto-populate from the Data control's column names and can be hidden, resized, and renamed by the application. Clicking a column header sorts the display. Selecting a row syncs the Data control's cursor position. The grid reads directly from the Data control's cached rows, so there is no separate copy of the data.
Header: widgets/widgetDbGrid.h
-Creation
+Creation
WidgetT *grid = wgtDbGrid(parent);
wgtDbGridSetDataWidget(grid, dataCtrl);Macros
+Macros
Macro Description ----- ----------- wgtDbGrid(parent) Create a database grid widget. @@ -4748,65 +4685,63 @@ wgtDbGridSetDataWidget(grid, dataCtrl);wgtDbGridSetColumnHeader(w, fieldName, header) Set a display header for a column (overrides the field name). wgtDbGridSetColumnWidth(w, fieldName, width) Set the width of a column by field name (tagged size, 0 = auto). wgtDbGridGetSelectedRow(w) Get the index of the currently selected data row (-1 if none). -
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- GridLines Boolean Read/Write Whether to draw grid lines between cells.-
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- Refresh Re-read the Data control and repaint.-
Events
+Events
Event Description ----- ----------- Click Fires when a row is clicked. DblClick Fires when a row is double-clicked. Default event.
Dropdown
-Dropdown
+Dropdown
A drop-down list that displays a single selected item and expands to show all options when clicked. Read-only selection (the user cannot type into it).
Header: widgets/widgetDropdown.h
-Creation
+Creation
WidgetT *dd = wgtDropdown(parent);
const char *items[] = { "Red", "Green", "Blue" };
wgtDropdownSetItems(dd, items, 3);Macros
+Macros
Macro Description ----- ----------- wgtDropdown(parent) Create a dropdown list. wgtDropdownSetItems(w, items, count) Set the list of items. items is a const char ** array. wgtDropdownGetSelected(w) Get the index of the selected item (-1 if none). wgtDropdownSetSelected(w, idx) Set the selected item by index.-
Events
+Events
Callback Description -------- ----------- onChange Fires when the selected item changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- ListIndex Integer Read/Write Index of the currently selected item.
ImageButton
-ImageButton
+ImageButton
A clickable button that displays an image instead of text. Has press/release visual feedback like a regular button. Can be created from raw pixel data or a BMP file.
Header: widgets/widgetImageButton.h
-Creation
+Creation
Macro Description ----- ----------- wgtImageButton(parent, data, w, h, pitch) Create an image button from raw pixel data. wgtImageButtonFromFile(parent, path) Create an image button by loading a BMP file.-
Methods
+Methods
Macro Description ----- ----------- wgtImageButtonSetData(w, data, imgW, imgH, pitch) Replace the image with new raw pixel data. wgtImageButtonLoadFile(w, path) Replace the image by loading a new file.-
Events
+Events
Callback Description -------- ----------- onClick Fires when the image button is clicked (press + release).-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Picture String Write-only Load an image from a file path. @@ -4815,25 +4750,24 @@ wgtDropdownSetItems(dd, items, 3);
Image
-Image
+Image
Displays a bitmap image. Can be created from raw pixel data or loaded from a BMP file on disk. The image is rendered at its natural size within the widget bounds.
Header: widgets/widgetImage.h
-Creation
+Creation
Macro Description ----- ----------- wgtImage(parent, data, w, h, pitch) Create an image widget from raw pixel data. data is a uint8_t * pixel buffer, w/h are dimensions, pitch is bytes per row. wgtImageFromFile(parent, path) Create an image widget by loading a BMP file from disk.-
Methods
+Methods
Macro Description ----- ----------- wgtImageSetData(w, data, imgW, imgH, pitch) Replace the displayed image with new raw pixel data. wgtImageLoadFile(w, path) Replace the displayed image by loading a new file.-
Events
+Events
Callback Description -------- ----------- onClick Fires when the image is clicked.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Picture String Write-only Load an image from a file path. @@ -4841,37 +4775,35 @@ wgtDropdownSetItems(dd, items, 3);ImageHeight Integer Read-only Height of the currently loaded image in pixels.
Label
-Label
+Label
A static text label. Does not accept keyboard focus. Typically used to describe other widgets. Supports text alignment and accelerator keys (with WCLASS_FOCUS_FORWARD, the accelerator moves focus to the next focusable sibling).
Header: widgets/widgetLabel.h
-Creation
+Creation
WidgetT *lbl = wgtLabel(parent, "Name:");Macros
+Macros
Macro Description ----- ----------- wgtLabel(parent, text) Create a text label. wgtLabelSetAlign(w, align) Set the text alignment (AlignStartE, AlignCenterE, AlignEndE).-
Properties
+Properties
Use wgtSetText() / wgtGetText() to change the text. Set accelKey for accelerator support (focus forwards to next focusable widget).
-Events
+Events
Labels use the common events only. Typically no callbacks are set on labels.
-Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Alignment Enum (Left, Center, Right) Read/Write Text alignment within the label.
ListBox
-ListBox
+ListBox
A scrollable list of text items. Supports single and multi-selection modes and drag-to-reorder.
Header: widgets/widgetListBox.h
-Creation
+Creation
WidgetT *lb = wgtListBox(parent);
const char *items[] = { "Alpha", "Beta", "Gamma" };
wgtListBoxSetItems(lb, items, 3);Macros
+Macros
Macro Description ----- ----------- wgtListBox(parent) Create a list box. @@ -4884,17 +4816,17 @@ wgtListBoxSetItems(lb, items, 3);wgtListBoxSelectAll(w) Select all items (multi-select mode). wgtListBoxClearSelection(w) Deselect all items. wgtListBoxSetReorderable(w, reorderable) Enable drag-to-reorder. -
Events
+Events
Callback Description -------- ----------- onClick Fires when an item is clicked. onDblClick Fires when an item is double-clicked. onChange Fires when the selection changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- ListIndex Integer Read/Write Index of the currently selected item.-
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- SelectAll Select all items. @@ -4906,11 +4838,10 @@ wgtListBoxSetItems(lb, items, 3);
ListView
-ListView
+ListView
A multi-column list with sortable headers. Supports single and multi-selection, column alignment, header click sorting, and drag-to-reorder. Data is provided as a flat array of strings (row-major order, one string per cell).
Header: widgets/widgetListView.h
-Creation
+Creation
WidgetT *lv = wgtListView(parent);
ListViewColT cols[] = {
{ "Name", wgtChars(20), ListViewAlignLeftE },
@@ -4919,19 +4850,19 @@ ListViewColT cols[] = {
wgtListViewSetColumns(lv, cols, 2);
const char *cells[] = { "file.txt", "1234", "readme.md", "5678" };
wgtListViewSetData(lv, cells, 2);Column Definition
+Column Definition
typedef struct {
const char *title;
int32_t width; // tagged size (wgtPixels/wgtChars/wgtPercent, 0 = auto)
ListViewAlignE align; // ListViewAlignLeftE, ListViewAlignCenterE, ListViewAlignRightE
} ListViewColT;Sort Direction
+Sort Direction
typedef enum {
ListViewSortNoneE,
ListViewSortAscE,
ListViewSortDescE
} ListViewSortE;Macros
+Macros
Macro Description ----- ----------- wgtListView(parent) Create a list view. @@ -4947,17 +4878,17 @@ wgtListViewSetData(lv, cells, 2);wgtListViewSelectAll(w) Select all rows. wgtListViewClearSelection(w) Deselect all rows. wgtListViewSetReorderable(w, reorderable) Enable drag-to-reorder of rows. -
Events
+Events
Callback Description -------- ----------- onClick Fires when a row is clicked. onDblClick Fires when a row is double-clicked. onChange Fires when the selection changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- ListIndex Integer Read/Write Index of the currently selected row.-
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- SelectAll Select all rows. @@ -4969,147 +4900,140 @@ wgtListViewSetData(lv, cells, 2);
ProgressBar
-ProgressBar
+ProgressBar
A visual indicator of progress, displayed as a filled bar. Supports both horizontal and vertical orientations. Value ranges from 0 to 100.
Header: widgets/widgetProgressBar.h
-Creation
+Creation
Macro Description ----- ----------- wgtProgressBar(parent) Create a horizontal progress bar. wgtProgressBarV(parent) Create a vertical progress bar.-
Methods
+Methods
Macro Description ----- ----------- wgtProgressBarSetValue(w, value) Set the progress value (0-100). wgtProgressBarGetValue(w) Get the current progress value.-
Events
+Events
ProgressBar is a display-only widget. Typically no callbacks are set.
-Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Value Integer Read/Write Current progress value (0-100).
Radio Button
-Radio Button
+Radio Button
A mutually exclusive selection control. Radio buttons must be placed inside a radio group container. Only one radio button within a group can be selected at a time.
Header: widgets/widgetRadio.h
-Creation
+Creation
WidgetT *grp = wgtRadioGroup(parent);
WidgetT *r1 = wgtRadio(grp, "Option A");
WidgetT *r2 = wgtRadio(grp, "Option B");Macros
+Macros
Macro Description ----- ----------- wgtRadioGroup(parent) Create a radio group container. wgtRadio(parent, text) Create a radio button inside a group. wgtRadioGroupSetSelected(w, idx) Set the selected radio button by index within the group. wgtRadioGetIndex(w) Get the index of the currently selected radio button.-
Events
+Events
Callback Description -------- ----------- onClick Fires on the radio button when clicked. onChange Fires when the selection changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Value Integer Read-only Index of the currently selected radio button in the group.-
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- SetSelected Set the selected radio button by index.
ScrollPane
-ScrollPane
+ScrollPane
A scrollable container that provides vertical and/or horizontal scrollbars when its content exceeds the visible area. Place a single child (typically a VBox or HBox) inside the scroll pane.
Header: widgets/widgetScrollPane.h
-Creation
+Creation
WidgetT *sp = wgtScrollPane(parent);
WidgetT *content = wgtVBox(sp);
// add children to content...Macros
+Macros
Macro Description ----- ----------- wgtScrollPane(parent) Create a scroll pane container. wgtScrollPaneScrollToChild(sp, child) Scroll so that the given child widget is visible. wgtScrollPaneSetNoBorder(w, noBorder) When true, removes the border around the scroll pane.-
Events
+Events
Callback Description -------- ----------- onScroll Fires when the scroll position changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- NoBorder Boolean Read/Write Whether the border around the scroll pane is hidden.
Separator
-Separator
+Separator
A visual dividing line used to separate groups of widgets. Available in horizontal and vertical orientations.
Header: widgets/widgetSeparator.h
-Creation
+Creation
Macro Description ----- ----------- wgtHSeparator(parent) Create a horizontal separator line. wgtVSeparator(parent) Create a vertical separator line.-
Events
+Events
Separator is a visual-only widget. No events.
Slider
-Slider
+Slider
A horizontal slider (track bar) for selecting an integer value within a range. The user drags the thumb or clicks the track to change the value.
Header: widgets/widgetSlider.h
-Creation
+Creation
WidgetT *sl = wgtSlider(parent, 0, 100);Macros
+Macros
Macro Description ----- ----------- wgtSlider(parent, minVal, maxVal) Create a slider with the given integer range. wgtSliderSetValue(w, value) Set the slider value programmatically. wgtSliderGetValue(w) Get the current slider value.-
Events
+Events
Callback Description -------- ----------- onChange Fires when the slider value changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Value Integer Read/Write Current slider value.
Spacer
-Spacer
+Spacer
An invisible widget used for layout purposes. By default it has weight=100, so it absorbs available extra space. Useful for pushing other widgets apart or aligning them to edges.
Header: widgets/widgetSpacer.h
-Creation
+Creation
WidgetT *row = wgtHBox(parent);
wgtButton(row, "OK");
wgtSpacer(row); // pushes Cancel to the right
wgtButton(row, "Cancel");Macro
+Macro
Macro Description ----- ----------- wgtSpacer(parent) Create an invisible spacer widget.-
Events
+Events
Spacer is an invisible layout widget. No events.
Spinner
-Spinner
+Spinner
A numeric input with up/down buttons for incrementing and decrementing a value within a range. Supports both integer and floating-point (real) modes.
Header: widgets/widgetSpinner.h
-Creation
+Creation
WidgetT *sp = wgtSpinner(parent, 0, 100, 1);Macros
+Macros
Macro Description ----- ----------- wgtSpinner(parent, minVal, maxVal, step) Create a spinner with the given integer range and step size. @@ -5123,17 +5047,17 @@ wgtButton(row, "Cancel");wgtSpinnerSetRealRange(w, minVal, maxVal) Set the floating-point range. wgtSpinnerSetRealStep(w, step) Set the floating-point step size. wgtSpinnerSetDecimals(w, decimals) Set the number of decimal places displayed in real mode. -
Events
+Events
Callback Description -------- ----------- onChange Fires when the value changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Value Integer Read/Write Current integer value. RealMode Boolean Read/Write Whether floating-point mode is active. Decimals Integer Read/Write Number of decimal places displayed in real mode.-
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- SetRange Set the integer range (min, max). @@ -5141,92 +5065,88 @@ wgtButton(row, "Cancel");
Splitter
-Splitter
+Splitter
A two-pane container with a draggable divider. The user drags the splitter bar to resize the two panes. Can be oriented vertically (left/right panes) or horizontally (top/bottom panes). Add exactly two children.
Header: widgets/widgetSplitter.h
-Creation
+Creation
WidgetT *sp = wgtSplitter(parent, true); // vertical = left|right
WidgetT *left = wgtVBox(sp);
WidgetT *right = wgtVBox(sp);Macros
+Macros
Macro Description ----- ----------- wgtSplitter(parent, vertical) Create a splitter. vertical=true for left/right panes, false for top/bottom. wgtSplitterSetPos(w, pos) Set the divider position in pixels. wgtSplitterGetPos(w) Get the current divider position in pixels.-
Events
+Events
Callback Description -------- ----------- onChange Fires when the divider position changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Position Integer Read/Write Divider position in pixels.
StatusBar
-StatusBar
+StatusBar
A horizontal bar typically placed at the bottom of a window for displaying status text and informational widgets. Children are laid out horizontally.
Header: widgets/widgetStatusBar.h
-Creation
+Creation
WidgetT *sb = wgtStatusBar(parent);
wgtLabel(sb, "Ready");Macro
+Macro
Macro Description ----- ----------- wgtStatusBar(parent) Create a status bar container.-
Properties
+Properties
Uses common container properties. Add child widgets (labels, progress bars, etc.) to populate.
-Events
+Events
StatusBar itself has no widget-specific events. Events fire on the child widgets.
TabControl
-TabControl
+TabControl
A tabbed container that displays one page at a time with clickable tabs along the top. Each tab page is a container that holds its own child widgets.
Header: widgets/widgetTabControl.h
-Creation
+Creation
WidgetT *tabs = wgtTabControl(parent);
WidgetT *page1 = wgtTabPage(tabs, "General");
WidgetT *page2 = wgtTabPage(tabs, "Advanced");
// add children to page1, page2...Macros
+Macros
Macro Description ----- ----------- wgtTabControl(parent) Create a tab control. wgtTabPage(parent, title) Add a tab page with the given title. Returns the page container widget. wgtTabControlSetActive(w, idx) Set the active tab by index (0-based). wgtTabControlGetActive(w) Get the index of the active tab.-
Events
+Events
Callback Description -------- ----------- onChange Fires when the active tab changes.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- TabIndex Integer Read/Write Index of the currently active tab (0-based).-
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- SetActive Set the active tab by index.
TextInput / TextArea
-TextInput / TextArea
+TextInput / TextArea
Single-line text input, password input, masked input, and multi-line text area with optional syntax colorization, line numbers, find/replace, and gutter decorators.
Header: widgets/widgetTextInput.h
-Creation
+Creation
Macro Description ----- ----------- wgtTextInput(parent, maxLen) Create a single-line text input. maxLen is the maximum number of characters. wgtPasswordInput(parent, maxLen) Create a password input (characters displayed as bullets). wgtMaskedInput(parent, mask) Create a masked input field. The mask string defines the input format. wgtTextArea(parent, maxLen) Create a multi-line text area.-
Methods (TextArea-specific)
+Methods (TextArea-specific)
Macro Description ----- ----------- wgtTextAreaSetColorize(w, fn, ctx) Set a syntax colorization callback. The callback receives each line and fills a color index array. Color indices: 0=default, 1=keyword, 2=string, 3=comment, 4=number, 5=operator, 6=type/builtin, 7=reserved. @@ -5241,7 +5161,7 @@ WidgetT *page2 = wgtTabPage(tabs, "Advanced"); wgtTextAreaSetLineDecorator(w, fn, ctx) Set a gutter line decorator callback. The callback returns a color and receives the line number, a color output pointer, and the user context. wgtTextAreaGetCursorLine(w) Get the current cursor line number. wgtTextAreaSetGutterClick(w, fn) Set a callback for gutter clicks (e.g. for breakpoint toggling). Callback receives the widget and line number.-
Events
+Events
Callback Description -------- ----------- onChange Fires when the text content changes. @@ -5250,15 +5170,14 @@ WidgetT *page2 = wgtTabPage(tabs, "Advanced");
Timer
-Timer
+Timer
A non-visual widget that fires its onClick callback at a regular interval. Useful for animations, polling, and periodic updates. Must be explicitly started after creation.
Header: widgets/widgetTimer.h
-Creation
+Creation
WidgetT *tmr = wgtTimer(parent, 1000, true); // 1 second, repeating
tmr->onClick = onTimerTick;
wgtTimerStart(tmr);Macros
+Macros
Macro Description ----- ----------- wgtTimer(parent, intervalMs, repeat) Create a timer. intervalMs is the interval in milliseconds. repeat: true for repeating, false for one-shot. @@ -5267,55 +5186,53 @@ wgtTimerStart(tmr);wgtTimerSetInterval(w, intervalMs) Change the timer interval. wgtTimerIsRunning(w) Returns true if the timer is currently running. wgtUpdateTimers() Global tick function. Called by the event loop to advance all active timers. -
Events
+Events
Callback Description -------- ----------- onClick Fires each time the timer elapses.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Enabled Boolean Read/Write Whether the timer is running. Reading returns the running state; writing starts or stops it. Interval Integer Write-only Timer interval in milliseconds.-
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- Start Start the timer. Stop Stop the timer.-
Extra Events (BASIC Interface)
+Extra Events (BASIC Interface)
Event Description ----- ----------- Timer Fires each time the timer elapses. Default event.
Toolbar
-Toolbar
+Toolbar
A horizontal container for toolbar buttons and controls. Typically placed at the top of a window. Children (usually ImageButtons or Buttons) are laid out horizontally with toolbar-appropriate spacing.
Header: widgets/widgetToolbar.h
-Creation
+Creation
WidgetT *tb = wgtToolbar(parent);
wgtImageButtonFromFile(tb, "icons/save.bmp");
wgtImageButtonFromFile(tb, "icons/open.bmp");Macro
+Macro
Macro Description ----- ----------- wgtToolbar(parent) Create a toolbar container.-
Properties
+Properties
Uses common container properties. Add children (buttons, separators, etc.) to populate the toolbar.
-Events
+Events
Toolbar itself has no widget-specific events. Events fire on the child widgets.
TreeView
-TreeView
+TreeView
A hierarchical tree control with expandable/collapsible nodes. Supports single and multi-selection and drag-to-reorder. Tree items are added as children of the TreeView or of other tree items to create nested hierarchies.
Header: widgets/widgetTreeView.h
-Creation
+Creation
WidgetT *tv = wgtTreeView(parent);
WidgetT *root = wgtTreeItem(tv, "Root");
WidgetT *child = wgtTreeItem(root, "Child");Macros
+Macros
Macro Description ----- ----------- wgtTreeView(parent) Create a tree view control. @@ -5328,13 +5245,13 @@ WidgetT *child = wgtTreeItem(root, "Child");wgtTreeItemIsExpanded(w) Check if a tree item is expanded. wgtTreeItemIsSelected(w) Check if a tree item is selected (multi-select mode). wgtTreeItemSetSelected(w, selected) Select or deselect a tree item. -
Events
+Events
Callback Description -------- ----------- onClick Fires when a tree item is clicked. onDblClick Fires when a tree item is double-clicked. onChange Fires when the selection changes.-
Methods (BASIC Interface)
+Methods (BASIC Interface)
Method Description ------ ----------- SetMultiSelect Enable or disable multi-selection. @@ -5342,30 +5259,29 @@ WidgetT *child = wgtTreeItem(root, "Child");
WrapBox
-WrapBox
+WrapBox
A flow/wrap layout container that arranges children left-to-right, wrapping to the next row when the available width is exceeded. Each row's height is the maximum child height in that row. Supports configurable spacing between items and rows, and per-row alignment for short rows.
Header: widgets/widgetWrapBox.h
-Creation
+Creation
WidgetT *wrap = wgtWrapBox(parent);
wgtButton(wrap, "Tag 1");
wgtButton(wrap, "Tag 2");
wgtButton(wrap, "Tag 3");Macro
+Macro
Macro Description ----- ----------- wgtWrapBox(parent) Create a wrap box container.-
Properties
+Properties
WrapBox uses the common WidgetT container fields for layout control:
Property Description -------- ----------- spacing Gap between children in both the horizontal and vertical directions (tagged size). Default is 4 pixels. padding Internal padding around children (tagged size). Default is 2 pixels.-
Properties (BASIC Interface)
+Properties (BASIC Interface)
Property Type Access Description -------- ---- ------ ----------- Alignment Enum (Left, Center, Right) Read/Write Row alignment for rows that do not fill the full width.-
Events
+Events
WrapBox is a container widget. It uses the common events only. No widget-specific events are defined.
data, '.');
+
+ if (dot) {
+ if (strcasecmp(dot, ".png") == 0) { mime = "image/png"; }
+ else if (strcasecmp(dot, ".jpg") == 0 ||
+ strcasecmp(dot, ".jpeg") == 0) { mime = "image/jpeg"; }
+ else if (strcasecmp(dot, ".gif") == 0) { mime = "image/gif"; }
+ }
+
+ // Alignment from record flags
+ const char *alignStyle = "";
+
+ if (rec->flags == HLP_IMG_CENTER) {
+ alignStyle = " style=\"text-align:center\"";
+ } else if (rec->flags == HLP_IMG_RIGHT) {
+ alignStyle = " style=\"text-align:right\"";
+ }
+
+ fprintf(f, "