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