DVX Widget Reference

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

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

Field	Type	Description
`name`	`char[32]`	Widget name for lookup via `wgtFind()`.
`x, y, w, h`	`int32_t`	Computed geometry relative to the window content area (set by layout).
`minW, minH`	`int32_t` (tagged)	Minimum size hints. Use `wgtPixels()`, `wgtChars()`, or `wgtPercent()`. 0 = auto.
`maxW, maxH`	`int32_t` (tagged)	Maximum size constraints. 0 = no limit.
`prefW, prefH`	`int32_t` (tagged)	Preferred size. 0 = auto.
`weight`	`int32_t`	Extra-space distribution weight. 0 = fixed, 100 = normal. A widget with weight=200 gets twice the extra space of one with weight=100.
`align`	`WidgetAlignE`	Main-axis alignment for children: `AlignStartE`, `AlignCenterE`, `AlignEndE`.
`spacing`	`int32_t` (tagged)	Spacing between children (containers only). 0 = default.
`padding`	`int32_t` (tagged)	Internal padding (containers only). 0 = default.
`fgColor`	`uint32_t`	Foreground color override. 0 = use color scheme default.
`bgColor`	`uint32_t`	Background color override. 0 = use color scheme default.
`visible`	`bool`	Visibility state.
`enabled`	`bool`	Enabled state. Disabled widgets are grayed out and ignore input.
`readOnly`	`bool`	Read-only mode: allows scrolling/selection but blocks editing.
`swallowTab`	`bool`	When true, Tab key goes to the widget instead of navigating focus.
`accelKey`	`char`	Lowercase accelerator character. 0 if none.
`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

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)

These callback function pointers are available on every WidgetT. Set them directly on the widget struct.

Callback	Signature	Description
`onClick`	`void ()(WidgetT w)`	Fires on mouse click / activation.
`onDblClick`	`void ()(WidgetT w)`	Fires on double-click.
`onChange`	`void ()(WidgetT w)`	Fires when the widget's value changes (text, selection, check state, etc.).
`onFocus`	`void ()(WidgetT w)`	Fires when the widget receives keyboard focus.
`onBlur`	`void ()(WidgetT w)`	Fires when the widget loses keyboard focus.
`onKeyPress`	`void ()(WidgetT w, int32_t keyAscii)`	Fires on a printable key press (ASCII value).
`onKeyDown`	`void ()(WidgetT w, int32_t keyCode, int32_t shift)`	Fires on key down (scan code + shift state).
`onKeyUp`	`void ()(WidgetT w, int32_t keyCode, int32_t shift)`	Fires on key up.
`onMouseDown`	`void ()(WidgetT w, int32_t button, int32_t x, int32_t y)`	Fires on mouse button press.
`onMouseUp`	`void ()(WidgetT w, int32_t button, int32_t x, int32_t y)`	Fires on mouse button release.
`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

Function	Description
`WidgetT wgtInitWindow(AppContextT ctx, WindowT *win)`	Initialize widgets for a window. Returns the root VBox container.
`AppContextT wgtGetContext(const WidgetT w)`	Walk up from any widget to retrieve the AppContextT.
`void wgtInvalidate(WidgetT *w)`	Mark widget for re-layout and repaint. Propagates to ancestors.
`void wgtInvalidatePaint(WidgetT *w)`	Mark widget for repaint only (no layout recalculation).
`void wgtSetText(WidgetT w, const char text)`	Set widget text (label, button, textinput, etc.).
`const char wgtGetText(const WidgetT w)`	Get widget text.
`void wgtSetEnabled(WidgetT *w, bool enabled)`	Enable or disable a widget.
`void wgtSetReadOnly(WidgetT *w, bool readOnly)`	Set read-only mode.
`void wgtSetFocused(WidgetT *w)`	Set keyboard focus to a widget.
`WidgetT *wgtGetFocused(void)`	Get the currently focused widget.
`void wgtSetVisible(WidgetT *w, bool visible)`	Show or hide a widget.
`void wgtSetName(WidgetT w, const char name)`	Set widget name for lookup.
`WidgetT wgtFind(WidgetT root, const char *name)`	Find a widget by name in the subtree.
`void wgtDestroy(WidgetT *w)`	Destroy a widget and all its children.
`void wgtSetTooltip(WidgetT w, const char text)`	Set tooltip text. Pass NULL to remove.

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

WidgetT *term = wgtAnsiTerm(parent, 80, 25);

Macros

Macro	Description
`wgtAnsiTerm(parent, cols, rows)`	Create an ANSI terminal widget with the given column and row dimensions.
`wgtAnsiTermWrite(w, data, len)`	Write raw bytes into the terminal's ANSI parser. `data` is a `const uint8_t *` buffer, `len` is the byte count.
`wgtAnsiTermClear(w)`	Clear the terminal screen and reset the cursor to the home position.
`wgtAnsiTermSetComm(w, ctx, readFn, writeFn)`	Attach a communication channel. `readFn` and `writeFn` are I/O callbacks; `ctx` is passed as their first argument.
`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)

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)

Method	Description
`Clear`	Clear the terminal screen.
`Write`	Write a string into the terminal.

Events

AnsiTerm uses the common events only. No widget-specific events are defined.

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

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

Box containers use the common WidgetT fields for layout control:

Property	Description
`align`	Main-axis alignment of children. HBox: Start=left, Center=center, End=right. VBox: Start=top, Center=center, End=bottom.
`spacing`	Gap between children (tagged size).
`padding`	Internal padding around children (tagged size).
`weight`	Controls how the box itself stretches within its parent.

Events

Containers use the common events only. No widget-specific events.

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

WidgetT *btn = wgtButton(parent, "OK");

Macro

Macro	Description
`wgtButton(parent, text)`	Create a push button with the given label text.

Properties

Uses common WidgetT properties. Set accelKey for keyboard shortcut. Use wgtSetText() / wgtGetText() to change the label.

Events

Callback	Description
`onClick`	Fires when the button is clicked (press + release).

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

WidgetT *lbl = wgtLabel(parent, "Name:");

Macros

Macro	Description
`wgtLabel(parent, text)`	Create a text label.
`wgtLabelSetAlign(w, align)`	Set the text alignment (`AlignStartE`, `AlignCenterE`, `AlignEndE`).

Properties

Use wgtSetText() / wgtGetText() to change the text. Set accelKey for accelerator support (focus forwards to next focusable widget).

Events

Labels use the common events only. Typically no callbacks are set on labels.

Properties (BASIC Interface)

Property	Type	Access	Description
`Alignment`	Enum (Left, Center, Right)	Read/Write	Text alignment within the label.

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

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)

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.
`wgtTextAreaGoToLine(w, line)`	Scroll to and place the cursor on the given line number.
`wgtTextAreaSetAutoIndent(w, enable)`	Enable or disable automatic indentation on newline.
`wgtTextAreaSetShowLineNumbers(w, show)`	Show or hide line numbers in the gutter.
`wgtTextAreaSetCaptureTabs(w, capture)`	When true, Tab key inserts a tab/spaces instead of moving focus.
`wgtTextAreaSetTabWidth(w, width)`	Set the tab stop width in characters.
`wgtTextAreaSetUseTabChar(w, useChar)`	When true, insert literal tab characters; when false, insert spaces.
`wgtTextAreaFindNext(w, needle, caseSens, fwd)`	Search for the next occurrence. Returns `true` if found.
`wgtTextAreaReplaceAll(w, needle, repl, caseSens)`	Replace all occurrences. Returns the number of replacements made.
`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

Callback	Description
`onChange`	Fires when the text content changes.
`onKeyPress`	Fires on each key press (ASCII value).
`onValidate`	Called before committing a change. Return false to cancel.

Checkbox

A toggle control with a text label. Clicking toggles between checked and unchecked states.

Header: widgets/widgetCheckbox.h

Creation

WidgetT *cb = wgtCheckbox(parent, "Enable logging");

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

Callback	Description
`onClick`	Fires when clicked (after toggle).
`onChange`	Fires when the checked state changes.

Properties (BASIC Interface)

Property	Type	Access	Description
`Value`	Boolean	Read/Write	Whether the checkbox is checked.

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

WidgetT *grp = wgtRadioGroup(parent);
WidgetT *r1  = wgtRadio(grp, "Option A");
WidgetT *r2  = wgtRadio(grp, "Option B");

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

Callback	Description
`onClick`	Fires on the radio button when clicked.
`onChange`	Fires when the selection changes.

Properties (BASIC Interface)

Property	Type	Access	Description
`Value`	Integer	Read-only	Index of the currently selected radio button in the group.

Methods (BASIC Interface)

Method	Description
`SetSelected`	Set the selected radio button by index.

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

WidgetT *dd = wgtDropdown(parent);
const char *items[] = { "Red", "Green", "Blue" };
wgtDropdownSetItems(dd, items, 3);

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

Callback	Description
`onChange`	Fires when the selected item changes.

Properties (BASIC Interface)

Property	Type	Access	Description
`ListIndex`	Integer	Read/Write	Index of the currently selected item.

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

WidgetT *cb = wgtComboBox(parent, 128);
const char *items[] = { "Arial", "Courier", "Times" };
wgtComboBoxSetItems(cb, items, 3);

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

Callback	Description
`onChange`	Fires when the text or selection changes.

Properties (BASIC Interface)

Property	Type	Access	Description
`ListIndex`	Integer	Read/Write	Index of the currently selected item.

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

WidgetT *data = wgtDataCtrl(parent);

Macros

Macro	Description
`wgtDataCtrl(parent)`	Create a Data control.
`wgtDataCtrlRefresh(w)`	Re-execute the RecordSource query and rebuild the row cache.
`wgtDataCtrlMoveFirst(w)`	Move the cursor to the first row.
`wgtDataCtrlMovePrev(w)`	Move the cursor to the previous row.
`wgtDataCtrlMoveNext(w)`	Move the cursor to the next row.
`wgtDataCtrlMoveLast(w)`	Move the cursor to the last row.
`wgtDataCtrlGetField(w, colName)`	Get the value of a column in the current row. Returns `const char *`.
`wgtDataCtrlSetField(w, colName, value)`	Set the value of a column in the current row (marks the row dirty).
`wgtDataCtrlUpdateRow(w)`	Write the current row's pending changes back to the database.
`wgtDataCtrlUpdate(w)`	Flush all pending changes to the database.
`wgtDataCtrlAddNew(w)`	Begin a new row. Sets dirty state; call Update to commit.
`wgtDataCtrlDelete(w)`	Delete the current row from the database.
`wgtDataCtrlSetMasterValue(w, val)`	Set the master-detail filter value for this control.
`wgtDataCtrlGetRowCount(w)`	Get the total number of cached rows.
`wgtDataCtrlGetColCount(w)`	Get the number of columns in the result set.
`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)

Property	Type	Access	Description
`DatabaseName`	String	Read/Write	Path to the SQLite database file.
`RecordSource`	String	Read/Write	SQL query or table name for the result set.
`KeyColumn`	String	Read/Write	Primary key column name (used for UPDATE/DELETE).
`MasterSource`	String	Read/Write	Name of the master Data control for master-detail linking.
`MasterField`	String	Read/Write	Column in the master control to read for the filter value.
`DetailField`	String	Read/Write	Column in this table to filter by the master value.
`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)

Method	Description
`AddNew`	Begin a new row.
`Delete`	Delete the current row.
`MoveFirst`	Move to the first row.
`MoveLast`	Move to the last row.
`MoveNext`	Move to the next row.
`MovePrevious`	Move to the previous row.
`Refresh`	Re-execute the query and rebuild the cache.
`Update`	Write pending changes to the database.

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

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

WidgetT *grid = wgtDbGrid(parent);
wgtDbGridSetDataWidget(grid, dataCtrl);

Macros

Macro	Description
`wgtDbGrid(parent)`	Create a database grid widget.
`wgtDbGridSetDataWidget(w, dataWidget)`	Bind the grid to a Data control. The grid reads rows from this widget.
`wgtDbGridRefresh(w)`	Re-read the Data control's state and repaint the grid.
`wgtDbGridSetColumnVisible(w, fieldName, visible)`	Show or hide a column by field name.
`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)

Property	Type	Access	Description
`GridLines`	Boolean	Read/Write	Whether to draw grid lines between cells.

Methods (BASIC Interface)

Method	Description
`Refresh`	Re-read the Data control and repaint.

Events

Event	Description
`Click`	Fires when a row is clicked.
`DblClick`	Fires when a row is double-clicked. Default event.

ListBox

A scrollable list of text items. Supports single and multi-selection modes and drag-to-reorder.

Header: widgets/widgetListBox.h

Creation

WidgetT *lb = wgtListBox(parent);
const char *items[] = { "Alpha", "Beta", "Gamma" };
wgtListBoxSetItems(lb, items, 3);

Macros

Macro	Description
`wgtListBox(parent)`	Create a list box.
`wgtListBoxSetItems(w, items, count)`	Set the list items.
`wgtListBoxGetSelected(w)`	Get the index of the selected item (-1 if none).
`wgtListBoxSetSelected(w, idx)`	Set the selected item by index.
`wgtListBoxSetMultiSelect(w, multi)`	Enable or disable multi-selection mode.
`wgtListBoxIsItemSelected(w, idx)`	Check if a specific item is selected (multi-select mode).
`wgtListBoxSetItemSelected(w, idx, selected)`	Select or deselect a specific item.
`wgtListBoxSelectAll(w)`	Select all items (multi-select mode).
`wgtListBoxClearSelection(w)`	Deselect all items.
`wgtListBoxSetReorderable(w, reorderable)`	Enable drag-to-reorder.

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)

Property	Type	Access	Description
`ListIndex`	Integer	Read/Write	Index of the currently selected item.

Methods (BASIC Interface)

Method	Description
`SelectAll`	Select all items.
`ClearSelection`	Deselect all items.
`SetMultiSelect`	Enable or disable multi-selection.
`SetReorderable`	Enable or disable drag-to-reorder.
`IsItemSelected`	Check if a specific item is selected by index.
`SetItemSelected`	Select or deselect a specific item by index.

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

WidgetT *lv = wgtListView(parent);
ListViewColT cols[] = {
    { "Name", wgtChars(20), ListViewAlignLeftE },
    { "Size", wgtChars(10), ListViewAlignRightE }
};
wgtListViewSetColumns(lv, cols, 2);
const char *cells[] = { "file.txt", "1234", "readme.md", "5678" };
wgtListViewSetData(lv, cells, 2);

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

typedef enum {
    ListViewSortNoneE,
    ListViewSortAscE,
    ListViewSortDescE
} ListViewSortE;

Macros

Macro	Description
`wgtListView(parent)`	Create a list view.
`wgtListViewSetColumns(w, cols, count)`	Define columns from an array of `ListViewColT`.
`wgtListViewSetData(w, cellData, rowCount)`	Set row data. `cellData` is a flat `const char *` array of size `rowCount colCount`.
`wgtListViewGetSelected(w)`	Get the index of the selected row (-1 if none).
`wgtListViewSetSelected(w, idx)`	Set the selected row by index.
`wgtListViewSetSort(w, col, dir)`	Set the sort column and direction.
`wgtListViewSetHeaderClickCallback(w, cb)`	Set a callback for header clicks. Signature: `void (cb)(WidgetT w, int32_t col, ListViewSortE dir)`.
`wgtListViewSetMultiSelect(w, multi)`	Enable or disable multi-selection.
`wgtListViewIsItemSelected(w, idx)`	Check if a specific row is selected.
`wgtListViewSetItemSelected(w, idx, selected)`	Select or deselect a specific row.
`wgtListViewSelectAll(w)`	Select all rows.
`wgtListViewClearSelection(w)`	Deselect all rows.
`wgtListViewSetReorderable(w, reorderable)`	Enable drag-to-reorder of rows.

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)

Property	Type	Access	Description
`ListIndex`	Integer	Read/Write	Index of the currently selected row.

Methods (BASIC Interface)

Method	Description
`SelectAll`	Select all rows.
`ClearSelection`	Deselect all rows.
`SetMultiSelect`	Enable or disable multi-selection.
`SetReorderable`	Enable or disable drag-to-reorder.
`IsItemSelected`	Check if a specific row is selected by index.
`SetItemSelected`	Select or deselect a specific row by index.

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

WidgetT *tv    = wgtTreeView(parent);
WidgetT *root  = wgtTreeItem(tv, "Root");
WidgetT *child = wgtTreeItem(root, "Child");

Macros

Macro	Description
`wgtTreeView(parent)`	Create a tree view control.
`wgtTreeItem(parent, text)`	Add a tree item as a child of the tree view or another tree item.
`wgtTreeViewGetSelected(w)`	Get the currently selected tree item (returns `WidgetT *`, NULL if none).
`wgtTreeViewSetSelected(w, item)`	Set the selected tree item.
`wgtTreeViewSetMultiSelect(w, multi)`	Enable or disable multi-selection.
`wgtTreeViewSetReorderable(w, reorderable)`	Enable drag-to-reorder of items.
`wgtTreeItemSetExpanded(w, expanded)`	Expand or collapse a tree item.
`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

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)

Method	Description
`SetMultiSelect`	Enable or disable multi-selection.
`SetReorderable`	Enable or disable drag-to-reorder.

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

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

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

Callback	Description
`onClick`	Fires when the image is clicked.

Properties (BASIC Interface)

Property	Type	Access	Description
`Picture`	String	Write-only	Load an image from a file path.
`ImageWidth`	Integer	Read-only	Width of the currently loaded image in pixels.
`ImageHeight`	Integer	Read-only	Height of the currently loaded image in pixels.

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

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

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

Callback	Description
`onClick`	Fires when the image button is clicked (press + release).

Properties (BASIC Interface)

Property	Type	Access	Description
`Picture`	String	Write-only	Load an image from a file path.
`ImageWidth`	Integer	Read-only	Width of the currently loaded image in pixels.
`ImageHeight`	Integer	Read-only	Height of the currently loaded image in pixels.

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

WidgetT *sl = wgtSlider(parent, 0, 100);

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

Callback	Description
`onChange`	Fires when the slider value changes.

Properties (BASIC Interface)

Property	Type	Access	Description
`Value`	Integer	Read/Write	Current slider value.

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

WidgetT *sp = wgtSpinner(parent, 0, 100, 1);

Macros

Macro	Description
`wgtSpinner(parent, minVal, maxVal, step)`	Create a spinner with the given integer range and step size.
`wgtSpinnerSetValue(w, value)`	Set the integer value.
`wgtSpinnerGetValue(w)`	Get the current integer value.
`wgtSpinnerSetRange(w, minVal, maxVal)`	Set the integer range.
`wgtSpinnerSetStep(w, step)`	Set the integer step size.
`wgtSpinnerSetRealMode(w, enable)`	Switch to floating-point mode.
`wgtSpinnerGetRealValue(w)`	Get the current floating-point value.
`wgtSpinnerSetRealValue(w, value)`	Set the floating-point value.
`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

Callback	Description
`onChange`	Fires when the value changes.

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)

Method	Description
`SetRange`	Set the integer range (min, max).
`SetStep`	Set the integer step size.

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

Macro	Description
`wgtProgressBar(parent)`	Create a horizontal progress bar.
`wgtProgressBarV(parent)`	Create a vertical progress bar.

Methods

Macro	Description
`wgtProgressBarSetValue(w, value)`	Set the progress value (0-100).
`wgtProgressBarGetValue(w)`	Get the current progress value.

Events

ProgressBar is a display-only widget. Typically no callbacks are set.

Properties (BASIC Interface)

Property	Type	Access	Description
`Value`	Integer	Read/Write	Current progress value (0-100).

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

WidgetT *cv = wgtCanvas(parent, 320, 200);

Macros

Macro	Description
`wgtCanvas(parent, w, h)`	Create a canvas with the given pixel dimensions.
`wgtCanvasClear(w, color)`	Fill the entire canvas with a solid color.
`wgtCanvasSetPenColor(w, color)`	Set the drawing pen color.
`wgtCanvasSetPenSize(w, size)`	Set the drawing pen size in pixels.
`wgtCanvasDrawLine(w, x0, y0, x1, y1)`	Draw a line from (x0,y0) to (x1,y1).
`wgtCanvasDrawRect(w, x, y, width, height)`	Draw a rectangle outline.
`wgtCanvasFillRect(w, x, y, width, height)`	Draw a filled rectangle.
`wgtCanvasFillCircle(w, cx, cy, radius)`	Draw a filled circle.
`wgtCanvasSetPixel(w, x, y, color)`	Set a single pixel to the given color.
`wgtCanvasGetPixel(w, x, y)`	Get the color of a single pixel.
`wgtCanvasDrawText(w, x, y, text)`	Draw text at the given position using the current pen color.
`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

Callback	Description
`onClick`	Fires when the canvas is clicked.
Mouse callback (set via `wgtCanvasSetMouseCallback`)	Fires on mouse down and drag with canvas-local coordinates.

Methods (BASIC Interface)

Method	Description
`Clear`	Clear the canvas to a given color.

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

WidgetT *tmr = wgtTimer(parent, 1000, true);  // 1 second, repeating
tmr->onClick = onTimerTick;
wgtTimerStart(tmr);

Macros

Macro	Description
`wgtTimer(parent, intervalMs, repeat)`	Create a timer. `intervalMs` is the interval in milliseconds. `repeat`: true for repeating, false for one-shot.
`wgtTimerStart(w)`	Start the timer.
`wgtTimerStop(w)`	Stop the timer.
`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

Callback	Description
`onClick`	Fires each time the timer elapses.

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)

Method	Description
`Start`	Start the timer.
`Stop`	Stop the timer.

Extra Events (BASIC Interface)

Event	Description
`Timer`	Fires each time the timer elapses. Default event.

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

WidgetT *tb = wgtToolbar(parent);
wgtImageButtonFromFile(tb, "icons/save.bmp");
wgtImageButtonFromFile(tb, "icons/open.bmp");

Macro

Macro	Description
`wgtToolbar(parent)`	Create a toolbar container.

Properties

Uses common container properties. Add children (buttons, separators, etc.) to populate the toolbar.

Events

Toolbar itself has no widget-specific events. Events fire on the child widgets.

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

WidgetT *sb = wgtStatusBar(parent);
wgtLabel(sb, "Ready");

Macro

Macro	Description
`wgtStatusBar(parent)`	Create a status bar container.

Properties

Uses common container properties. Add child widgets (labels, progress bars, etc.) to populate.

Events

StatusBar itself has no widget-specific events. Events fire on the child widgets.

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

WidgetT *sp = wgtScrollPane(parent);
WidgetT *content = wgtVBox(sp);
// add children to content...

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

Callback	Description
`onScroll`	Fires when the scroll position changes.

Properties (BASIC Interface)

Property	Type	Access	Description
`NoBorder`	Boolean	Read/Write	Whether the border around the scroll pane is hidden.

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

WidgetT *sp = wgtSplitter(parent, true);  // vertical = left|right
WidgetT *left  = wgtVBox(sp);
WidgetT *right = wgtVBox(sp);

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

Callback	Description
`onChange`	Fires when the divider position changes.

Properties (BASIC Interface)

Property	Type	Access	Description
`Position`	Integer	Read/Write	Divider position in pixels.

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

WidgetT *tabs = wgtTabControl(parent);
WidgetT *page1 = wgtTabPage(tabs, "General");
WidgetT *page2 = wgtTabPage(tabs, "Advanced");
// add children to page1, page2...

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

Callback	Description
`onChange`	Fires when the active tab changes.

Properties (BASIC Interface)

Property	Type	Access	Description
`TabIndex`	Integer	Read/Write	Index of the currently active tab (0-based).

Methods (BASIC Interface)

Method	Description
`SetActive`	Set the active tab by index.

Separator

A visual dividing line used to separate groups of widgets. Available in horizontal and vertical orientations.

Header: widgets/widgetSeparator.h

Creation

Macro	Description
`wgtHSeparator(parent)`	Create a horizontal separator line.
`wgtVSeparator(parent)`	Create a vertical separator line.

Events

Separator is a visual-only widget. No events.

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

WidgetT *row = wgtHBox(parent);
wgtButton(row, "OK");
wgtSpacer(row);           // pushes Cancel to the right
wgtButton(row, "Cancel");

Macro

Macro	Description
`wgtSpacer(parent)`	Create an invisible spacer widget.

Events

Spacer is an invisible layout widget. No events.

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

WidgetT *wrap = wgtWrapBox(parent);
wgtButton(wrap, "Tag 1");
wgtButton(wrap, "Tag 2");
wgtButton(wrap, "Tag 3");

Macro

Macro	Description
`wgtWrapBox(parent)`	Create a wrap box container.

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)

Property	Type	Access	Description
`Alignment`	Enum (Left, Center, Right)	Read/Write	Row alignment for rows that do not fill the full width.

Events

WrapBox is a container widget. It uses the common events only. No widget-specific events are defined.

DVX Widget Reference -- Generated from source headers in core/dvxWidget.h and widgets/*.h.

DVX Widget Reference

Table of Contents

Base WidgetT (Common Properties, Events, and Operations)

Common Properties

Size Specification Macros

Common Events (Callbacks)

Common Operations

AnsiTerm

Creation

Macros

Properties (BASIC Interface)

Methods (BASIC Interface)

Events

Box (VBox / HBox / Frame)

Creation

Properties

Events

Button

Creation

Macro

Properties

Events

Label

Creation

Macros

Properties

Events

Properties (BASIC Interface)

TextInput / TextArea

Creation

Methods (TextArea-specific)

Events

Checkbox

Creation

Macros

Events

Properties (BASIC Interface)

Radio Button

Creation

Macros

Events

Properties (BASIC Interface)

Methods (BASIC Interface)

Dropdown

Creation

Macros

Events

Properties (BASIC Interface)

ComboBox

Creation

Macros

Events

Properties (BASIC Interface)

DataCtrl

Creation

Macros

Properties (BASIC Interface)

Methods (BASIC Interface)

Events

DbGrid

Creation

Macros

Properties (BASIC Interface)

Methods (BASIC Interface)

Events

ListBox

Creation

Macros

Events

Properties (BASIC Interface)

Methods (BASIC Interface)

ListView

Creation

Column Definition

Sort Direction

Macros

Events

Properties (BASIC Interface)

Methods (BASIC Interface)

TreeView