.section Widgets
.topic widget.base
.title Base WidgetT (Common Properties, Events, and Operations)
.toc 0 Widget System
.default
.index WidgetT
.index Widget Base
.index Common Properties
.index Common Events

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

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

.h3 Common Properties

.table
  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.
.endtable

.h3 Size Specification Macros

.index wgtPixels
.index wgtChars
.index wgtPercent

.table
  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.
.endtable

.h3 Common Events (Callbacks)

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

.index onClick
.index onChange
.index onKeyPress
.index onKeyDown
.index onMouseDown

.table
  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.
.endtable

.h3 Common Operations

.index wgtInitWindow
.index wgtGetContext
.index wgtInvalidate
.index wgtSetText
.index wgtGetText
.index wgtSetEnabled
.index wgtSetFocused
.index wgtSetVisible
.index wgtFind
.index wgtDestroy

.table
  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.
.endtable
