add(examples/errors): error notifaction handling

build.zig

@@ -17,6 +17,8 @@ pub fn build(b: *std.Build) void {
         // styles:
         text,
         palette,
+        // error handling
+        errors,
     };
 
     const example = b.option(Examples, "example", "Example to build and/or run. (default: vertical)") orelse .vertical;
@@ -115,6 +117,15 @@ pub fn build(b: *std.Build) void {
     });
     text.root_module.addImport("zterm", lib);
 
+    // error handling:
+    const errors = b.addExecutable(.{
+        .name = "errors",
+        .root_source_file = b.path("examples/errors.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    errors.root_module.addImport("zterm", lib);
+
     // mapping of user selected example to compile step
     const exe = switch (example) {
         // elements:
@@ -129,6 +140,8 @@ pub fn build(b: *std.Build) void {
         // styles:
         .text => text,
         .palette => palette,
+        // error handling:
+        .errors => errors,
     };
     b.installArtifact(exe);
 

examples/errors.zig

@@ -0,0 +1,153 @@
+const std = @import("std");
+const zterm = @import("zterm");
+
+const App = zterm.App(union(enum) {});
+
+const log = std.log.scoped(.default);
+
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
+
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
+
+    pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+        _ = ctx;
+        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+
+        const row = 2;
+        const col = size.cols / 2 -| (text.len / 2);
+        const anchor = (row * size.cols) + col;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.bg = .black;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE: do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+        }
+    }
+};
+
+const InfoText = struct {
+    const text = "Press any key; Non-Ascii inputs (i.e. `Enter` or `Backspace`) to trigger an exception";
+
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
+
+    pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+        _ = ctx;
+        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+
+        const row = 2;
+        const col = size.cols / 2 -| (text.len / 2);
+        const anchor = (row * size.cols) + col;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.bg = .black;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE: do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+        }
+    }
+};
+
+const ErrorNotification = struct {
+    msg: ?[]const u8 = null,
+
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .handle = handle, .content = content } };
+    }
+
+    pub fn handle(ctx: *anyopaque, event: App.Event) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        switch (event) {
+            .key => |key| if (!key.isAscii()) return error.UnsupportedKey,
+            .resize => |_| {},
+            .err => |err| this.msg = err.msg,
+            else => {},
+        }
+    }
+
+    pub 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.msg) |msg| {
+            const row = size.rows -| 2;
+            const col = size.cols -| 2 -| msg.len;
+            const anchor = (row * size.cols) + col;
+
+            for (msg, 0..) |cp, idx| {
+                cells[anchor + idx].style.fg = .white;
+                cells[anchor + idx].style.bg = .black;
+                cells[anchor + idx].cp = cp;
+
+                // NOTE: do not write over the contents of this `Container`'s `Size`
+                if (anchor + idx == cells.len - 1) break;
+            }
+
+            this.msg = null;
+        }
+    }
+};
+
+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 quit_text: QuitText = .{};
+    var info_text: InfoText = .{};
+    var error_notification: ErrorNotification = .{};
+
+    var container = try App.Container.init(allocator, .{
+        .layout = .{
+            .gap = 2,
+            .padding = .{ .top = 5, .bottom = 3, .left = 3, .right = 3 },
+        },
+    }, quit_text.element());
+    defer container.deinit();
+
+    try container.append(try App.Container.init(allocator, .{}, info_text.element()));
+    try container.append(try App.Container.init(allocator, .{}, error_notification.element()));
+
+    try app.start();
+    defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
+
+    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(),
+            .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();
+    }
+}