Base WidgetT (Common Properties, Events, and Operations)
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
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)
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 (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
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
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
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
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
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
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
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
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
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.