Zig ImGui

https://github.com/zig-gamedev/zgui
Admin
Zig build package and bindings for https://github.com/ocornut/imgui and optional extras.
Tokens:3,339
Snippets:14
Trust Score:7.3
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Implement ImGuiNodeEditor Functionality in Zig

Source: https://github.com/zig-gamedev/zgui/blob/main/README.md

This code demonstrates the basic setup and usage of the zgui wrapper for ImGuiNodeEditor. It includes creating an editor context, defining a simple node, and adding input/output pins.

```zig
var node_editor = zgui.node_editor.EditorContext.create(.{ .enable_smooth_zoom = true });

zgui.node_editor.setCurrentEditor(node_editor);
defer zgui.node_editor.setCurrentEditor(null);
{
    zgui.node_editor.begin("NodeEditor", .{ 0, 0 });
    defer zgui.node_editor.end();

    zgui.node_editor.beginNode(1);
    {
        defer zgui.node_editor.endNode();

        zgui.textUnformatted("Node A");

        zgui.node_editor.beginPin(1, .input);
        {
            defer zgui.node_editor.endPin();
            zgui.textUnformatted("-> In");
        }

        zgui.sameLine(.{});

        zgui.node_editor.beginPin(2, .output);
        {
            defer zgui.node_editor.endPin();
            zgui.textUnformatted("Out ->");
        }
    }
}
```

--------------------------------

### Configure zgui and dependencies in Zig build.zig

Source: https://github.com/zig-gamedev/zgui/blob/main/README.md

This snippet demonstrates how to integrate `zgui` and its rendering backends (`zglfw`, `zpool`, `zgpu`) into a Zig project's `build.zig` file. It shows how to add dependencies, import modules, and link libraries for a complete setup, enabling features like ImPlot.

```zig
pub fn build(b: *std.Build) void {
    const exe = b.addExecutable(.{ ... });

    const zgui = b.dependency("zgui", .{
        .shared = false,
        .with_implot = true,
    });
    exe.root_module.addImport("zgui", zgui.module("root"));
    exe.linkLibrary(zgui.artifact("imgui"));
    
    { // Needed for glfw/wgpu rendering backend
        const zglfw = b.dependency("zglfw", .{});
        exe.root_module.addImport("zglfw", zglfw.module("root"));
        exe.linkLibrary(zglfw.artifact("glfw"));

        const zpool = b.dependency("zpool", .{});
        exe.root_module.addImport("zpool", zpool.module("root"));

        const zgpu = b.dependency("zgpu", .{});
        exe.root_module.addImport("zgpu", zgpu.module("root"));
        exe.linkLibrary(zgpu.artifact("zdawn"));
    }
}
```

--------------------------------

### Initialize zgui in Zig executable for shared library setup

Source: https://github.com/zig-gamedev/zgui/blob/main/README.md

When `zgui` dependencies are built as a shared library, this snippet shows how to initialize `zgui` in the executable. It uses `zgui.init` for standard context management and `zgui.deinit` for proper cleanup upon application exit.

```zig
const zgui = @import("zgui");
zgui.init(allocator);
defer zgui.deinit();
```

--------------------------------

### Create and Configure ImPlot Line Plots in Zig

Source: https://github.com/zig-gamedev/zgui/blob/main/README.md

This example illustrates how to use the zgui plot API to create and configure line plots. It shows setting up axes, limits, legends, and plotting both single-value and XY data.

```zig
if (zgui.plot.beginPlot("Line Plot", .{ .h = -1.0 })) {
    zgui.plot.setupAxis(.x1, .{ .label = "xaxis" });
    zgui.plot.setupAxisLimits(.x1, .{ .min = 0, .max = 5 });
    zgui.plot.setupLegend(.{ .south = true, .west = true }, .{});
    zgui.plot.setupFinish();
    zgui.plot.plotLineValues("y data", i32, .{ .v = &.{ 0, 1, 0, 1, 0, 1 } });
    zgui.plot.plotLine("xy data", f32, .{
        .xv = &.{ 0.1, 0.2, 0.5, 2.5 },
        .yv = &.{ 0.1, 0.3, 0.5, 0.9 },
    });
    zgui.plot.endPlot();
}
```

--------------------------------

### Utilize Str Member Functions for String Manipulation

Source: https://github.com/zig-gamedev/zgui/blob/main/libs/imgui_test_engine/thirdparty/Str/README.md

Shows common member functions of the `Str` class for setting, appending, and referencing strings. It includes examples of formatted string operations (`setf`, `appendf`) and setting a reference to a literal (`set_ref`).

```C++
Str256 s;
s.set("hello sailor");                   // set (copy)
s.setf("%s/%s.tmp", folder, filename);   // set (w/format)
s.append("hello");                       // append. cost a length() calculation!
s.appendf("hello %d", 42);               // append (w/format). cost a length() calculation!
s.set_ref("Hey!");                       // set (literal/reference, just copy pointer, no tracking)
```

--------------------------------

### Implement zgui main loop for UI rendering in Zig

Source: https://github.com/zig-gamedev/zgui/blob/main/README.md

This snippet illustrates the typical main loop structure for a `zgui` application. It includes `newFrame` for starting a new UI frame, various `zgui` widgets like `bulletText`, `button`, and `dragFloat` for user interaction, and finally `draw` to render the UI onto the specified render pass.

```zig
// Main loop
while (...) {
    zgui.backend.newFrame(framebuffer_width, framebuffer_height);

    zgui.bulletText(
        "Average :  {d:.3} ms/frame ({d:.1} fps)",
        .{ demo.gctx.stats.average_cpu_time, demo.gctx.stats.fps },
    );
    zgui.bulletText("W, A, S, D :  move camera", .{});
    zgui.spacing();

    if (zgui.button("Setup Scene", .{})) {
        // Button pressed.
    }

    if (zgui.dragFloat("Drag 1", .{ .v = &value0 })) {
        // value0 has changed
    }

    if (zgui.dragFloat("Drag 2", .{ .v = &value0, .min = -1.0, .max = 1.0 })) {
        // value1 has changed
    }

    // Setup wgpu render pass here

    zgui.backend.draw(pass);
}
```

--------------------------------

### Utilize zgui DrawList API for custom graphics in Zig

Source: https://github.com/zig-gamedev/zgui/blob/main/README.md

This code showcases various drawing functions available through the `zgui` DrawList API. It includes examples for drawing quads, text with formatting, filled and unfilled circles, and polylines, demonstrating vector graphics capabilities for custom widgets and visualizations.

```zig
draw_list.addQuad(.{
    .p1 = .{ 170, 420 },
    .p2 = .{ 270, 420 },
    .p3 = .{ 220, 520 },
    .p4 = .{ 120, 520 },
    .col = 0xff_00_00_ff,
    .thickness = 3.0,
});
draw_list.addText(.{ 130, 130 }, 0xff_00_00_ff, "The number is: {}", .{7});
draw_list.addCircleFilled(.{ .p = .{ 200, 600 }, .r = 50, .col = 0xff_ff_ff_ff });
draw_list.addCircle(.{ .p = .{ 200, 600 }, .r = 30, .col = 0xff_00_00_ff, .thickness = 11 });
draw_list.addPolyline(
    &.{ .{ 100, 700 }, .{ 200, 600 }, .{ 300, 700 }, .{ 400, 600 } },
    .{ .col = 0xff_00_aa_11, .thickness = 7 },
);
```

--------------------------------

### Initialize and set up zgui in Zig application

Source: https://github.com/zig-gamedev/zgui/blob/main/README.md

This code shows the basic initialization of `zgui` with an allocator and font loading. It also demonstrates how to initialize the `zgui` backend with window and graphics context details (device, swapchain format, depth format), preparing it for rendering.

```zig
const zgui = @import("zgui");

zgui.init(allocator);

_ = zgui.io.addFontFromFile(content_dir ++ "Roboto-Medium.ttf", 16.0);

zgui.backend.init(
    window,
    demo.gctx.device,
    @enumToInt(swapchain_format),
    @enumToInt(depth_format),
);
```

--------------------------------

### Use Str Constructor Helpers for Formatted and Reference Strings

Source: https://github.com/zig-gamedev/zgui/blob/main/libs/imgui_test_engine/thirdparty/Str/README.md

Illustrates the use of constructor helpers like `Str256f` for formatted string construction and `StrRef` for creating string references without allocation or copying. It demonstrates how these can be used directly as function parameters.

```C++
// Constructor helper for format string:
Str256f filename("%s/%s.tmp", folder, filename);             // construct (w/format)
fopen(Str256f("%s/%s.tmp, folder, filename).c_str(), "rb");  // construct (w/format), use as function param, destruct

// Constructor helper for reference/literal:
StrRef ref("literal");                   // copy pointer, no allocation, no string copy
StrRef ref2(GetDebugName());             // copy pointer. no tracking of anything whatsoever, know what you are doing!
```

--------------------------------

### Register and Run ImGUI Test Engine Tests in Zig

Source: https://github.com/zig-gamedev/zgui/blob/main/README.md

This snippet demonstrates how to register and run automated tests using the zgui wrapper for ImGUI Test Engine. It covers defining GUI interactions within a test context and asserting conditions.

```zig
var check_b = false;
var _te: *zgui.te.TestEngine = zgui.te.getTestEngine().?;
fn registerTests() void {
    _ = _te.registerTest(
        "Awesome",
        "should_do_some_another_magic",
        @src(),
        struct {
            pub fn gui(ctx: *zgui.te.TestContext) !void {
                _ = ctx; // autofix
                _ = zgui.begin("Test Window", .{ .flags = .{ .no_saved_settings = true } });
                defer zgui.end();

                zgui.text("Hello, automation world", .{});
                _ = zgui.button("Click Me", .{});
                if (zgui.treeNode("Node")) {
                    defer zgui.treePop();

                    _ = zgui.checkbox("Checkbox", .{ .v = &check_b });
                }
            }

            pub fn run(ctx: *zgui.te.TestContext) !void {
                ctx.setRef("/Test Window");
                ctx.windowFocus("");

                ctx.itemAction(.click, "Click Me", .{}, null);
                ctx.itemAction(.open, "Node", .{}, null);
                ctx.itemAction(.check, "Node/Checkbox", .{}, null);
                ctx.itemAction(.uncheck, "Node/Checkbox", .{}, null);

                std.testing.expect(true) catch |err| {
                    zgui.te.checkTestError(@src(), err);
                    return;
                };
            }
        },
    );
}
```

--------------------------------

### Initialize Str with and without Local Buffer

Source: https://github.com/zig-gamedev/zgui/blob/main/libs/imgui_test_engine/thirdparty/Str/README.md

Demonstrates how `Str` instances are initialized, showing the difference between using a heap-allocated string (no local buffer) and strings that fit into a pre-defined local buffer (`Str16`, `Str256`). It highlights how the `sizeof()` changes based on the local buffer size.

```C++
// No local buffer, always use heap, sizeof()==8~16
Str s = "hey";   // use heap

// With a local buffer of 16 bytes, sizeof() == 8~16 + 16 bytes.
Str16 s = "filename.h"; // copy into local buffer
Str16 s = "long_filename_not_very_long_but_longer_than_expected.h";   // use heap

// With a local buffer of 256 bytes, sizeof() == 8~16 + 256 bytes.
Str256 s = "long_filename_not_very_long_but_longer_than_expected.h";  // copy into local buffer
```

--------------------------------

### Str Class API Reference

Source: https://github.com/zig-gamedev/zgui/blob/main/libs/imgui_test_engine/thirdparty/Str/README.md

Provides an overview of the `Str` class and its derived types, detailing their purpose, inheritance, and key characteristics like local buffer capacity and overhead. It also lists the main member functions and constructor helpers.

```APIDOC
Class: Str
  Description: Base C++ string type with optional local buffer.
  Properties:
    - capacity: (internal) 21 bits for max 2MB string size.
    - local_buffer_size: (internal) 10 bits for max 1023 bytes local buffer.
    - overhead: 8-bytes (32-bit), 16-bytes (64-bit).
  Derived Classes:
    - StrXXX (e.g., Str16, Str256):
      Description: Derived from Str, instances hold specific local buffer capacity.
      Usage: Can be passed to functions expecting Str& or Str* due to inheritance.

Methods:
  - set(const char* str):
      Description: Copies the given string into the Str instance.
      Parameters:
        - str: (const char*) The string to copy.
  - setf(const char* fmt, ...):
      Description: Formats and copies a string using printf-style formatting.
      Parameters:
        - fmt: (const char*) Format string.
        - ...: (variadic) Arguments for formatting.
  - append(const char* str):
      Description: Appends the given string. Incurs a length() calculation cost.
      Parameters:
        - str: (const char*) The string to append.
  - appendf(const char* fmt, ...):
      Description: Formats and appends a string. Incurs a length() calculation cost.
      Parameters:
        - fmt: (const char*) Format string.
        - ...: (variadic) Arguments for formatting.
  - set_ref(const char* str):
      Description: Sets the Str to reference a literal/external string. No allocation, no tracking.
      Parameters:
        - str: (const char*) The literal or external string to reference.

Constructor Helpers:
  - StrXXXf(const char* fmt, ...):
      Description: Constructor helper for formatted strings (e.g., Str256f).
      Parameters:
        - fmt: (const char*) Format string.
        - ...: (variadic) Arguments for formatting.
  - StrRef(const char* str):
      Description: Constructor helper for literal/reference strings. Copies pointer only, no allocation, no tracking.
      Parameters:
        - str: (const char*) The literal or external string to reference.
```

--------------------------------

### Initialize zgui in Zig shared library without context

Source: https://github.com/zig-gamedev/zgui/blob/main/README.md

This snippet demonstrates how to initialize `zgui` within a shared library when the ImGui context resides in the shared library. It uses `zgui.initNoContext` and `zgui.deinitNoContxt` as the `zgui` Zig code requires its own separate memory buffer.

```zig
const zgui = @import("zgui");
zgui.initNoContext(allocator);
defer zgui.deinitNoContxt();
```

--------------------------------

### Demonstrate Polymorphic Usage of Str Base Type

Source: https://github.com/zig-gamedev/zgui/blob/main/libs/imgui_test_engine/thirdparty/Str/README.md

Explains that `StrXXX` types derive from `Str`, allowing them to be passed to functions expecting a base `Str` type. This enables polymorphic behavior where the local buffer of the derived type is utilized if available.

```C++
void MyFunc(Str& s) { s = "Hello"; }     // will use local buffer if available in Str instance
```
Tokens:
Raw