AI_Slop/DVX_GUI
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documentation update.

Browse source
This commit is contained in:
Scott Duensing 2026-03-12 22:12:25 -05:00
parent 0a06d8f354
commit 5f3aec3144
1 changed files with 112 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

115
dvx/README.md
View file

@ -53,6 +53,24 @@ Supporting files:
| `thirdparty/stb_image.h` | Third-party single-header image loader | | `thirdparty/stb_image.h` | Third-party single-header image loader |
| `thirdparty/stb_image_write.h` | Third-party single-header image writer | | `thirdparty/stb_image_write.h` | Third-party single-header image writer |
The widget system lives in `widgets/`:
| File | Purpose |
|------|---------|
| `widgets/widgetInternal.h` | Shared internal header: vtable type, constants, cross-widget prototypes |
| `widgets/widgetClass.c` | Widget class table: one `WidgetClassT` vtable entry per widget type |
| `widgets/widgetCore.c` | Allocation, tree ops, hit testing, flag-based type queries |
| `widgets/widgetLayout.c` | Two-pass layout engine (measure + arrange) |
| `widgets/widgetEvent.c` | Mouse, keyboard, scroll, resize, and paint event dispatch |
| `widgets/widgetOps.c` | Paint dispatcher, public operations (`wgtFind`, `wgtDestroy`, etc.) |
| `widgets/widget*.c` | One file per widget type (button, checkbox, slider, etc.) |
Each widget type is self-contained in its own `.c` file. Dispatch for
paint, layout, mouse, keyboard, getText/setText, and destroy is driven
by a per-type vtable (`WidgetClassT`) rather than switch statements in
the core files. Adding a new widget type requires only a new `.c` file
and an entry in the class table.
## Quick start ## Quick start
```c ```c
@ -343,6 +361,54 @@ int32_t textWidth(const BitmapFontT *font, const char *text);
Draw text using the built-in 8-pixel-wide bitmap font. `opaque` controls Draw text using the built-in 8-pixel-wide bitmap font. `opaque` controls
whether background pixels are drawn. `drawChar` returns the advance width. whether background pixels are drawn. `drawChar` returns the advance width.
```c
void drawTermRow(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font,
int32_t x, int32_t y, int32_t cols,
const uint8_t *lineData, const uint32_t *palette,
bool blinkVisible, int32_t cursorCol);
```
Bulk-render a row of terminal character cells. `lineData` points to
`(char, attr)` byte pairs (2 bytes per cell). `palette` is a 16-entry
packed-color table. `blinkVisible` controls blink attribute visibility.
`cursorCol` is the column to draw inverted (-1 for no cursor). This is
much faster than calling `drawChar` per cell because clip bounds are
computed once for the whole row and there is no per-character function
call overhead.
```c
char accelParse(const char *text);
```
Parse an accelerator key from text with `&` markers (e.g. `"E&xit"` returns
`'x'`). Returns the lowercase accelerator character, or 0 if none found.
```c
void drawTextAccel(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font,
int32_t x, int32_t y, const char *text,
uint32_t fg, uint32_t bg, bool opaque);
int32_t textWidthAccel(const BitmapFontT *font, const char *text);
```
Draw/measure text with `&` accelerator processing. The character after `&`
is underlined. `&&` produces a literal `&`. `textWidthAccel` returns the
width in pixels, excluding `&` markers.
```c
void drawFocusRect(DisplayT *d, const BlitOpsT *ops,
int32_t x, int32_t y, int32_t w, int32_t h,
uint32_t color);
```
Draw a dotted rectangle outline (every other pixel). Used to indicate
keyboard focus on widgets.
```c
void drawMaskedBitmap(DisplayT *d, const BlitOpsT *ops,
int32_t x, int32_t y, int32_t w, int32_t h,
const uint16_t *andMask, const uint16_t *xorData,
uint32_t fgColor, uint32_t bgColor);
```
Draw a 1-bit bitmap with AND/XOR masks (used for mouse cursors). Each row
is a `uint16_t`. Pixels where the AND mask is 0 are drawn using the XOR
data to select `fgColor` or `bgColor`.
```c ```c
void drawHLine(DisplayT *d, const BlitOpsT *ops, void drawHLine(DisplayT *d, const BlitOpsT *ops,
int32_t x, int32_t y, int32_t w, uint32_t color); int32_t x, int32_t y, int32_t w, uint32_t color);
@ -545,6 +611,8 @@ WidgetT *wgtTreeView(WidgetT *parent);
WidgetT *wgtTreeItem(WidgetT *parent, const char *text); WidgetT *wgtTreeItem(WidgetT *parent, const char *text);
void wgtTreeItemSetExpanded(WidgetT *w, bool expanded); void wgtTreeItemSetExpanded(WidgetT *w, bool expanded);
bool wgtTreeItemIsExpanded(const WidgetT *w); bool wgtTreeItemIsExpanded(const WidgetT *w);
WidgetT *wgtTreeViewGetSelected(const WidgetT *w);
void wgtTreeViewSetSelected(WidgetT *w, WidgetT *item);
``` ```
Hierarchical tree with expand/collapse support. Create a tree view, then Hierarchical tree with expand/collapse support. Create a tree view, then
add items as children. Nest items by adding them as children of other add items as children. Nest items by adding them as children of other
@ -559,6 +627,9 @@ scrolling on trough clicks.
Default weight is 100. Set `onClick` on individual tree items to handle Default weight is 100. Set `onClick` on individual tree items to handle
selection, or `onChange` to be notified of expand/collapse. selection, or `onChange` to be notified of expand/collapse.
`wgtTreeViewGetSelected` returns the currently selected tree item (or NULL).
`wgtTreeViewSetSelected` sets the selection programmatically.
### Image ### Image
```c ```c
@ -683,9 +754,22 @@ via `writeFn` (arrows become `ESC[A`..`ESC[D`, etc.).
int32_t wgtAnsiTermPoll(WidgetT *w); int32_t wgtAnsiTermPoll(WidgetT *w);
``` ```
Poll the comm interface for incoming data and process it through the Poll the comm interface for incoming data and process it through the
ANSI parser. Returns the number of bytes read. Call this from your ANSI parser. Also handles cursor blink and text blink timers. Returns
event loop or idle handler, then `wgtInvalidate()` if the return the number of bytes read. When using `dvxUpdate()`, terminal polling
value is nonzero. is handled automatically -- call this manually only when running your
own event loop.
```c
int32_t wgtAnsiTermRepaint(WidgetT *w, int32_t *outY, int32_t *outH);
```
Fast repaint: renders only dirty rows directly into the window's content
buffer, bypassing the full widget paint pipeline (no clear, no relayout,
no other widgets). Returns the number of rows repainted (0 if nothing
was dirty). If `outY` and `outH` are non-NULL, they receive the
content-buffer-relative Y coordinate and height of the repainted region,
for targeted dirty-rect invalidation. Uses `drawTermRow()` internally
for efficient bulk rendering. When using `dvxUpdate()`, this is called
automatically after `wgtAnsiTermPoll()`.
```c ```c
void wgtAnsiTermSetScrollback(WidgetT *w, int32_t maxLines); void wgtAnsiTermSetScrollback(WidgetT *w, int32_t maxLines);
@ -777,6 +861,31 @@ When enabled, draws 1px neon-colored borders around all layout containers
so their bounds are visible. Each container gets a distinct color derived so their bounds are visible. Each container gets a distinct color derived
from its pointer. from its pointer.
### Layout and paint internals
These are called automatically by `wgtInvalidate()`, but are available
for manual use when embedding the widget system in a custom event loop.
```c
int32_t wgtResolveSize(int32_t taggedSize, int32_t parentSize, int32_t charWidth);
```
Convert a tagged size (from `wgtPixels`, `wgtChars`, or `wgtPercent`) to
a pixel value given the parent's size and the font's character width.
```c
void wgtLayout(WidgetT *root, int32_t availW, int32_t availH,
const BitmapFontT *font);
```
Run the two-pass layout engine on the widget tree: measure minimum sizes
bottom-up, then distribute available space top-down. Sets `x`, `y`, `w`,
`h` on every widget.
```c
void wgtPaint(WidgetT *root, DisplayT *d, const BlitOpsT *ops,
const BitmapFontT *font, const ColorSchemeT *colors);
```
Paint the entire widget tree into the window's content buffer.
### List box operations ### List box operations
```c ```c