reykjalin.org
Immediate mode renderer for libvaxis
update readme, as well as the demo
+58
-2
README.md
+58
-2
README.md
···
1
1
# vxim
2
2
3
-
vxim is currently just an experiment to make an immediate-mode framework for [libvaxis](https://github.com/rockorager/libvaxis).
3
+
vxim is currently an experiment to make an immediate-mode framework for [libvaxis](https://github.com/rockorager/libvaxis). If it turns out to be viable — and it's very promising so far! — I plan to use this for writing the TUI for my editor project: [Fönn](https://tangled.org/@reykjalin.org/fn).
4
4
5
-
Doesn't do much yet, but here's a demo of the current capabilities:
5
+
## Demo
6
6
7
7
8
8
9
+
Code for the recording is in [src/demo.zig](./src/demo.zig).
10
+
11
+
## Features
12
+
13
+
The framework isn't very feature complete, and likely won't be for some time. I plan to add widgets as I need them while working on [Fönn](https://tangled.org/@reykjalin.org/fn), but contributions are welcome!
14
+
15
+
Current widgets included:
16
+
* `button`
17
+
* `text`
18
+
* `window`
19
+
* `padding`
20
+
* `menuBar`
21
+
22
+
All widgets handle mouse events and focus automatically. They have some minor customization options, but for the most part they're pretty limited at the moment.
23
+
24
+
## Contributing
25
+
26
+
Contributions are welcome through [GitHub pull requests](https://github.com/reykjalin/vxim), [Tangled pulls](https://tangled.org/@reykjalin.org/vxim), or email patches.
27
+
28
+
## Implementation details
29
+
30
+
The implementation of `vxim` draws heavily from [DVUI](https://github.com/david-vanderson/dvui), but with a distinct flavor that fits better with how `libvaxis` works.
31
+
32
+
The biggest difference is that `vxim` does not render frames in a continuous loop, queue up events, and then send them all at once to the update function. Instead, the update function you pass to `vxim` will only get called when the terminal receives an event you've subscribed to.
33
+
34
+
This means `vxim` doesn't operate on a "frame", and as such isn't like (most?) other immediate mode UI libraries, like DVUI, Dear Imgui, and others. Instead it's entirely event based and connected to interactions with the terminal. That said, using `vxim` still feels like using a regular immediate mode library.
35
+
36
+
### Widget IDs
37
+
38
+
Every focusable widget must have an ID. Unlike DVUI — which uses [@src()](https://ziglang.org/documentation/0.15.2/#toc-src) and the widget hierarchy to generate widget IDs — you can make up a type for your widget IDs and pass it to `vxim`. It'll then be used by all the widget functions in `vxim`.
39
+
40
+
I recommend a simple enum:
41
+
42
+
```zig
43
+
enum Widget {
44
+
AppWindow,
45
+
OkButton,
46
+
CancelButton,
47
+
}
48
+
```
49
+
50
+
but you can go as crazy with this as you'd like.
51
+
52
+
### Mouse focus and clicks
53
+
54
+
To handle clicks properly, without them bleeding through elements stacked on top of one another, I borrowed the concept of what I've called "mouse focus" from DVUI — a different name, but same concept.
55
+
56
+
Whenever a mouse click is performed each widget will receive a `.mouse_focus` event. If a widget receives this event it'll be set as the currently mouse-focused widget. Once the `.mouse_focus` event has been sent, it'll be immediately followed by the `.mouse` click event.
57
+
58
+
What this does is ensure that the last element drawn in the update loop will be mouse-focused by the time we send the `.mouse` click event on the next call to the update function. Clicks are only processed for the element that currently has mouse focus.
59
+
60
+
#### Known bugs with mouse focus and clicks
61
+
62
+
There is currently [a bug](https://tangled.org/@reykjalin.org/vxim/issues/8) in the implementation that means you must subscribe to `.mouse_focus` by including it in your event struct so that the event gets delivered to all the widgets you're using. If you don't, focus won't be handled correctly and clicks won't be delivered at all. This should be a compile-time error, but it currently is not.
63
+
64
+
I plan to fix this soon.
assets/demo.gif
assets/demo.gif
This is a binary file and will not be displayed.