search

david-vanderson / dvui

Other
413 stars 33 forks source link

readme

DVUI - Immediate Zig GUI for Apps and Games

A Zig GUI toolkit for whole applications or extra debugging windows in an existing application.

Tested with Zig 0.13

How to run the built-in examples:

Online Docs This document is a broad overview. See implementation details for how to write and modify widgets.

Online discussion happens in #gui-dev on the zig discord server: https://discord.gg/426ZADhs

Below is a screenshot of the demo window, whose source code can be found at src/Examples.zig.

Screenshot of DVUI Standalone Example (Application Window)

Projects using DVUI

Features

Usage

DVUI Demo is a template project you can use as a starting point.

The build.zig and build.zig.zon files there show how to reference dvui as a zig dependency.

Built-in Widgets

Design

Immediate Mode

if (try dvui.button(@src(), "Ok", .{}, .{})) {
  dialog.close();
}

Widgets are not stored between frames like in traditional gui toolkits (gtk, win32, cocoa). dvui.button() processes input events, draws the button on the screen, and returns true if a button click happened this frame.

For an intro to immediate mode guis, see: https://github.com/ocornut/imgui/wiki#about-the-imgui-paradigm

Advantages

Drawbacks

Handle All Events

DVUI processes every input event, making it useable in low framerate situations. A button can receive a mouse-down event and a mouse-up event in the same frame and correctly report a click. A custom button could even report multiple clicks per frame. (the higher level dvui.button() function only reports 1 click per frame)

In the same frame these can all happen:

Because everything is in a single pass, this works in the normal case where widget A is run before widget B. It doesn't work in the opposite order (widget B receives a tab that moves focus to A) because A ran before it got focus.

Floating Windows

This library can be used in 2 ways:

Floating windows and popups are handled by deferring their rendering so that they render properly on top of windows below them. Rendering of all floating windows and popups happens during window.end().

FPS throttling

If your app is running at a fixed framerate, use window.begin() and window.end() which handle bookkeeping and rendering.

If you want to only render frames when needed, add window.beginWait() at the start and window.waitTime() at the end. These cooperate to sleep the right amount and render frames when:

window.waitTime() also accepts a max fps parameter which will ensure the framerate stays below the given value.

window.beginWait() and window.waitTime() maintain an internal estimate of how much time is spent outside of the rendering code. This is used in the calculation for how long to sleep for the next frame.

The estimate is visible in the demo window Animations > Clock > "Estimate of frame overhead". The estimate is only updated on frames caused by a timer expiring (like the clock example), and it starts at 1ms.

Widget init and deinit

The easiest way to use widgets is through the high-level functions that create and install them:

{
    var box = try dvui.box(@src(), .vertical, .{.expand = .both});
    defer box.deinit();

    // widgets run here will be children of box
}

These functions allocate memory for the widget onto an internal arena allocator that is flushed each frame.

Instead you can allocate the widget on the stack using the lower-level functions:

{
    var box = BoxWidget.init(@src(), .vertical, false, .{.expand = .both});
    // box now has an id, can look up animations/timers

    try box.install();
    // box is now parent widget

    try box.drawBackground();
    // might draw the background in a different way

    defer box.deinit();

    // widgets run here will be children of box
}

The lower-level functions give a lot more customization options including animations, intercepting events, and drawing differently.

Start with the high-level functions, and when needed, copy the body of the high-level function and customize from there.

Parent, Child, and Layout

The primary layout mechanism is nesting widgets. DVUI keeps track of the current parent widget. When a widget runs, it is a child of the current parent. A widget may then make itself the current parent, and reset back to the previous parent when it runs deinit().

The parent widget decides what rectangle of the screen to assign to each child.

Usually you want each part of a gui to either be packed tightly (take up only min size), or expand to take the available space. The choice might be different for vertical vs. horizontal.

When a child widget is laid out (sized and positioned), it sends 2 pieces of info to the parent:

If parent is not expanded, the intent is to pack as tightly as possible, so it will give all children only their min size.

If parent has more space than the children need, it will lay them out using the hints:

Appearance

Each widget has the following options that can be changed through the Options struct when creating the widget:

Each widget has its own default options. These can be changed directly:

dvui.ButtonWidget.defaults.background = false;

Themes can be changed between frames or even within a frame. The theme controls the fonts and colors referenced by font_style and named colors.

if (theme_dark) {
    win.theme = &dvui.Theme.AdwaitaDark;
}
else {
    win.theme = &dvui.Theme.AdwaitaLight;
}

The theme's color_accent is also used to show keyboard focus.

See implementation details for more information.