119 lines
6.9 KiB
Text
119 lines
6.9 KiB
Text
.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
|