add(examples/layout): vertical, horizontal and grid

examples/elements/input.zig

@@ -0,0 +1,128 @@
+const std = @import("std");
+const zterm = @import("zterm");
+
+const App = zterm.App(union(enum) {
+    accept: []u21,
+});
+
+const log = std.log.scoped(.default);
+
+pub const InputField = struct {
+    input: std.ArrayList(u21),
+    queue: *App.Queue,
+
+    pub fn init(allocator: std.mem.Allocator, queue: *App.Queue) @This() {
+        return .{
+            .input = .init(allocator),
+            .queue = queue,
+        };
+    }
+
+    pub fn deinit(this: @This()) void {
+        this.input.deinit();
+    }
+
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                .handle = handle,
+                .content = content,
+            },
+        };
+    }
+
+    fn handle(ctx: *anyopaque, event: App.Event) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        switch (event) {
+            .key => |key| {
+                if (key.isAscii()) try this.input.append(key.cp);
+
+                if (key.eql(.{ .cp = zterm.input.Enter }) or key.eql(.{ .cp = zterm.input.KpEnter }))
+                    this.queue.push(.{ .accept = try this.input.toOwnedSlice() });
+
+                if (key.eql(.{ .cp = zterm.input.Backspace }) or key.eql(.{ .cp = zterm.input.Delete }) or key.eql(.{ .cp = zterm.input.KpDelete }))
+                    _ = this.input.pop();
+            },
+            else => {},
+        }
+    }
+
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+
+        if (this.input.items.len == 0) return;
+
+        const row: u16 = 1;
+        const col: u16 = 1;
+
+        for (this.input.items, 0..) |cp, idx| {
+            cells[(row * size.cols) + col + idx].style.fg = .black;
+            cells[(row * size.cols) + col + idx].cp = cp;
+
+            // NOTE: do not write over the contents of this `Container`'s `Size`
+            if ((row * size.cols) + col + idx == cells.len - 1) break;
+        }
+    }
+};
+
+pub fn main() !void {
+    errdefer |err| log.err("Application Error: {any}", .{err});
+
+    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) {
+        log.err("memory leak", .{});
+    };
+
+    const allocator = gpa.allocator();
+
+    var app: App = .init;
+    var renderer = zterm.Renderer.Buffered.init(allocator);
+    defer renderer.deinit();
+
+    var input_field: InputField = .init(allocator, &app.queue);
+    defer input_field.deinit();
+
+    const element = input_field.element();
+
+    var container = try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .grey },
+        .layout = .{ .padding = .all(5) },
+    }, .{});
+    defer container.deinit();
+
+    try container.append(try App.Container.init(allocator, .{ .rectangle = .{ .fill = .light_grey } }, element));
+
+    try app.start();
+    defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
+
+    // event loop
+    while (true) {
+        const event = app.nextEvent();
+        log.debug("received event: {s}", .{@tagName(event)});
+
+        switch (event) {
+            .init => continue,
+            .quit => break,
+            .resize => |size| try renderer.resize(size),
+            .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
+            .accept => |input| {
+                defer allocator.free(input);
+                log.info("Accepted input {any}", .{input});
+            },
+            .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
+            else => {},
+        }
+
+        container.handle(event) catch |err| app.postEvent(.{
+            .err = .{
+                .err = err,
+                .msg = "Container Event handling failed",
+            },
+        });
+
+        try renderer.render(@TypeOf(container), &container);
+        try renderer.flush();
+    }
+}

examples/elements/scrollable.zig

@@ -0,0 +1,178 @@
+const std = @import("std");
+const zterm = @import("zterm");
+
+const input = zterm.input;
+const App = zterm.App(union(enum) {});
+
+const log = std.log.scoped(.default);
+
+pub const HelloWorldText = packed struct {
+    const text = "Hello World";
+
+    text_color: zterm.Color = .black,
+
+    // example function to create the interface instance for this `Element` implementation
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                .handle = handle,
+                .content = content,
+            },
+        };
+    }
+
+    // example function to render contents for a `Container`
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+
+        // NOTE: error should only be returned here in case an in-recoverable exception has occurred
+        const row = size.rows / 2;
+        const col = size.cols / 2 -| (text.len / 2);
+
+        for (0.., text) |idx, char| {
+            cells[(row * size.cols) + col + idx].style.fg = this.text_color;
+            cells[(row * size.cols) + col + idx].cp = char;
+        }
+    }
+
+    // example function to handle events for a `Container`
+    fn handle(ctx: *anyopaque, event: App.Event) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        switch (event) {
+            .init => log.debug(".init event", .{}),
+            .key => |key| if (key.eql(.{ .cp = input.Space })) {
+                var next_color_idx = @intFromEnum(this.text_color);
+                next_color_idx += 1;
+                next_color_idx %= 17;
+                if (next_color_idx == @intFromEnum(zterm.Color.default)) next_color_idx += 1;
+                this.text_color = @enumFromInt(next_color_idx);
+                log.debug("Next color: {s}", .{@tagName(this.text_color)});
+            },
+            else => {},
+        }
+    }
+};
+
+pub fn main() !void {
+    errdefer |err| log.err("Application Error: {any}", .{err});
+
+    // TODO: maybe create own allocator as some sort of arena allocator to have consistent memory usage
+    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    defer {
+        const deinit_status = gpa.deinit();
+        if (deinit_status == .leak) {
+            log.err("memory leak", .{});
+        }
+    }
+    const allocator = gpa.allocator();
+
+    var app: App = .init;
+    var renderer = zterm.Renderer.Buffered.init(allocator);
+    defer renderer.deinit();
+
+    var element_wrapper: HelloWorldText = .{};
+    const element = element_wrapper.element();
+
+    var box = try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .blue },
+        .layout = .{
+            .gap = 1,
+            .direction = .vertical,
+            .padding = .vertical(1),
+        },
+        .min_size = .{ .rows = 50 },
+    }, .{});
+    try box.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .light_green },
+    }, .{}));
+    try box.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .light_green },
+    }, element));
+    try box.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .light_green },
+    }, .{}));
+    defer box.deinit();
+
+    var scrollable: App.Scrollable = .{
+        .container = box,
+        .vertical = true,
+    };
+
+    var container = try App.Container.init(allocator, .{
+        .border = .{
+            .separator = .{
+                .enabled = true,
+                .line = .double,
+            },
+        },
+        .layout = .{
+            .gap = 2,
+            .padding = .all(5),
+            .direction = .horizontal,
+        },
+    }, .{});
+    try container.append(try App.Container.init(allocator, .{}, scrollable.element()));
+
+    try container.append(try App.Container.init(allocator, .{
+        .border = .{
+            .color = .light_blue,
+            .sides = .vertical,
+        },
+    }, .{}));
+    try container.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .blue },
+    }, .{}));
+    defer container.deinit(); // also de-initializes the children
+
+    try app.start();
+    defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
+
+    // event loop
+    while (true) {
+        const event = app.nextEvent();
+        log.debug("received event: {s}", .{@tagName(event)});
+
+        switch (event) {
+            .init => {
+                try container.handle(event);
+                continue; // do not render
+            },
+            .quit => break,
+            .resize => |size| try renderer.resize(size),
+            .key => |key| {
+                if (key.eql(.{ .cp = 'q' })) app.quit();
+
+                // corresponding element could even be changed from the 'outside' (not forced through the event system)
+                // event system however allows for cross element communication (i.e. broadcasting messages, etc.)
+                if (key.eql(.{ .cp = input.Escape })) element_wrapper.text_color = .black;
+
+                if (key.eql(.{ .cp = 'n', .mod = .{ .ctrl = true } })) {
+                    try app.interrupt();
+                    defer app.start() catch @panic("could not start app event loop");
+                    var child = std.process.Child.init(&.{"hx"}, allocator);
+                    _ = child.spawnAndWait() catch |err| app.postEvent(.{
+                        .err = .{
+                            .err = err,
+                            .msg = "Spawning $EDITOR failed",
+                        },
+                    });
+                }
+            },
+            // NOTE: errors could be displayed in another container in case one was received, etc. to provide the user with feedback
+            .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
+            else => {},
+        }
+
+        // NOTE: returned errors should be propagated back to the application
+        container.handle(event) catch |err| app.postEvent(.{
+            .err = .{
+                .err = err,
+                .msg = "Container Event handling failed",
+            },
+        });
+        try renderer.render(@TypeOf(container), &container);
+        try renderer.flush();
+    }
+}