add: .line core event for line contents in non *raw mode* instead of .key core events

The end of the `.line` event received contents is highlighted by a trailing newline
(which cannot occur before, as that triggers the line event itself).

Add signal handler for SIGCONT which forces a `.resize` event that should re-draw the
contents after continuing a suspended application (i.e. ctrl+z followed by `fg`).

examples/direct.zig

@@ -1,3 +1,76 @@
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
+
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                .minSize = minSize,
+                .content = content,
+            },
+        };
+    }
+
+    fn minSize(_: *anyopaque, _: *const App.Model, size: zterm.Point) zterm.Point {
+        return .{ .x = size.x, .y = 10 }; // this includes the border
+    }
+
+    pub fn content(ctx: *anyopaque, _: *const App.Model, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        const y = 0;
+        const x = size.x / 2 -| (text.len / 2);
+        const anchor = (y * size.x) + x;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.emphasis = &.{.bold};
+            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 Prompt = struct {
+    len: u16 = 5,
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                // .minSize = minSize,
+                .content = content,
+            },
+        };
+    }
+
+    // NOTE size hint is not required as the `.size = .{ .dim = .{..} }` property is set accordingly which denotes the minimal size
+    // fn minSize(ctx: *anyopaque, _: *const App.Model, _: zterm.Point) zterm.Point {
+    //     const this: *@This() = @ptrCast(@alignCast(ctx));
+    //     return .{ .x = this.len, .y = 1 };
+    // }
+
+    pub fn content(ctx: *anyopaque, _: *const App.Model, cells: []zterm.Cell, size: zterm.Point) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        assert(cells.len > 2); // expect at least two cells
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        for (0..this.len) |idx| {
+            cells[idx].style.bg = .red;
+            cells[idx].style.fg = .black;
+            cells[idx].style.emphasis = &.{.bold};
+        }
+        cells[this.len - 1].style.cursor = true; // marks the actual end of the rendering!
+
+        const anchor = 1;
+        cells[anchor + 0].cp = 'N';
+        cells[anchor + 1].cp = 'O';
+        cells[anchor + 2].cp = 'R';
+    }
+};
+
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
@@ -11,29 +84,42 @@ pub fn main() !void {
     defer renderer.deinit();
 
     var container: App.Container = try .init(gpa, .{
-        .border = .{
-            .sides = .all,
-        },
         .layout = .{
-            .direction = .horizontal,
-            .separator = .{ .enabled = true },
+            .direction = .vertical,
         },
         .size = .{
-            .dim = .{ .y = 30 },
             .grow = .horizontal_only,
         },
     }, .{});
     defer container.deinit();
 
-    try container.append(try .init(gpa, .{
+    var quit_text: QuitText = .{};
+    var intermediate: App.Container = try .init(gpa, .{
+        .border = .{
+            .sides = .all,
+        },
+        .layout = .{
+            .direction = .horizontal,
+        },
+    }, quit_text.element());
+    try intermediate.append(try .init(gpa, .{
         .rectangle = .{ .fill = .blue },
     }, .{}));
 
-    try container.append(try .init(gpa, .{
+    try intermediate.append(try .init(gpa, .{
         .rectangle = .{ .fill = .green },
     }, .{}));
+    try container.append(intermediate);
 
-    try app.start(); // needs to become configurable, as what should be enabled / disabled (i.e. show cursor, hide cursor, use alternate screen, etc.)
+    var prompt: Prompt = .{};
+    try container.append(try .init(gpa, .{
+        .rectangle = .{ .fill = .red },
+        .size = .{
+            .dim = .{ .y = 1 },
+        },
+    }, prompt.element()));
+
+    try app.start(.direct); // needs to become configurable, as what should be enabled / disabled (i.e. show cursor, hide cursor, use alternate screen, etc.)
     defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
 
     // event loop
@@ -49,14 +135,14 @@ pub fn main() !void {
         // handle events
         for (0..len) |_| {
             const event = app.queue.pop();
-            //log.debug("received event: {s}", .{@tagName(event)});
+            log.debug("received event: {s}", .{@tagName(event)});
 
             // pre event handling
             switch (event) {
                 // NOTE maybe I want to decouple the `key`s from the user input too? i.e. this only makes sense if the output is not echoed!
                 // otherwise just use gnu's `readline`?
-                .key => |key| {
-                    if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit();
+                .line => |line| {
+                    log.debug("{s}", .{line});
                 },
                 // 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 }),

src/app.zig

@@ -30,7 +30,29 @@ pub fn App(comptime M: type, comptime E: type) type {
         thread: ?Thread = null,
         quit_event: Thread.ResetEvent,
         termios: ?posix.termios = null,
-        winch_registered: bool = false,
+        handler_registered: bool = false,
+        config: TerminalConfiguration,
+
+        pub const TerminalConfiguration = struct {
+            altScreen: bool,
+            saveScreen: bool,
+            rawMode: bool,
+            hideCursor: bool,
+
+            pub const full: @This() = .{
+                .altScreen = true,
+                .saveScreen = true,
+                .rawMode = true,
+                .hideCursor = true,
+            };
+
+            pub const direct: @This() = .{
+                .altScreen = false,
+                .saveScreen = false,
+                .rawMode = false,
+                .hideCursor = false,
+            };
+        };
 
         // global variable for the registered handler for WINCH
         var handler_ctx: *anyopaque = undefined;
@@ -41,6 +63,13 @@ pub fn App(comptime M: type, comptime E: type) type {
             // -> the signal might not work correctly when hosting the application over ssh!
             this.postEvent(.resize);
         }
+        /// registered CONT handler to force a complete redraw
+        fn handleCont(_: i32) callconv(.c) void {
+            const this: *@This() = @ptrCast(@alignCast(handler_ctx));
+            // NOTE this does not have to be done if in-band resize events are supported
+            // -> the signal might not work correctly when hosting the application over ssh!
+            this.postEvent(.resize);
+        }
 
         pub fn init(io: std.Io, model: Model) @This() {
             return .{
@@ -48,44 +77,50 @@ pub fn App(comptime M: type, comptime E: type) type {
                 .model = model,
                 .queue = .{},
                 .quit_event = .{},
+                .config = undefined,
             };
         }
 
-        pub fn start(this: *@This()) !void {
+        pub fn start(this: *@This(), config: TerminalConfiguration) !void {
+            this.config = config;
             if (this.thread) |_| return;
 
             // post init event (as the very first element to be in the queue - event loop)
             this.postEvent(.init);
 
-            if (!this.winch_registered) {
+            if (!this.handler_registered) {
                 handler_ctx = this;
-                var act = posix.Sigaction{
+                posix.sigaction(posix.SIG.WINCH, &.{
                     .handler = .{ .handler = handleWinch },
                     .mask = posix.sigemptyset(),
                     .flags = 0,
-                };
-                posix.sigaction(posix.SIG.WINCH, &act, null);
-                this.winch_registered = true;
+                }, null);
+                posix.sigaction(posix.SIG.CONT, &.{
+                    .handler = .{ .handler = handleCont },
+                    .mask = posix.sigemptyset(),
+                    .flags = 0,
+                }, null);
+                this.handler_registered = true;
             }
 
             this.quit_event.reset();
             this.thread = try Thread.spawn(.{}, @This().run, .{this});
 
-            //var termios: posix.termios = undefined;
-            //try terminal.enableRawMode(&termios);
-            //if (this.termios) |_| {} else this.termios = termios;
+            var termios: posix.termios = undefined;
+            if (this.config.rawMode) try terminal.enableRawMode(&termios);
+            if (this.termios) |_| {} else this.termios = termios;
 
-            //try terminal.enterAltScreen();
-            //try terminal.saveScreen();
-            //try terminal.hideCursor();
-            //try terminal.enableMouseSupport();
+            if (this.config.altScreen) try terminal.enterAltScreen();
+            if (this.config.saveScreen) try terminal.saveScreen();
+            if (this.config.hideCursor) try terminal.hideCursor();
+            if (this.config.altScreen and this.config.rawMode) try terminal.enableMouseSupport();
         }
 
         pub fn interrupt(this: *@This()) !void {
             this.quit_event.set();
-            //try terminal.disableMouseSupport();
-            //try terminal.restoreScreen();
-            //try terminal.exitAltScreen();
+            if (this.config.altScreen and this.config.rawMode) try terminal.disableMouseSupport();
+            if (this.config.saveScreen) try terminal.restoreScreen();
+            if (this.config.altScreen) try terminal.exitAltScreen();
             if (this.thread) |*thread| {
                 thread.join();
                 this.thread = null;
@@ -94,13 +129,10 @@ pub fn App(comptime M: type, comptime E: type) type {
 
         pub fn stop(this: *@This()) !void {
             try this.interrupt();
+            if (this.config.hideCursor) try terminal.showCursor();
+            if (this.config.saveScreen) try terminal.resetCursor();
             if (this.termios) |termios| {
-                try terminal.disableMouseSupport();
-                try terminal.showCursor();
-                try terminal.resetCursor();
-                try terminal.restoreScreen();
-                try terminal.disableRawMode(&termios);
-                try terminal.exitAltScreen();
+                if (this.config.rawMode) try terminal.disableRawMode(&termios);
                 this.termios = null;
             }
         }
@@ -416,9 +448,14 @@ pub fn App(comptime M: type, comptime E: type) type {
                                 var len = read_bytes;
                                 while (!std.unicode.utf8ValidateSlice(buf[0..len])) len -= 1;
                                 remaining_bytes = read_bytes - len;
+                                if (this.config.rawMode) {
                                     var iter: std.unicode.Utf8Iterator = .{ .bytes = buf[0..len], .i = 0 };
                                     while (iter.nextCodepoint()) |cp| this.postEvent(.{ .key = .{ .cp = cp } });
                                     continue;
+                                } else {
+                                    this.postEvent(.{ .line = buf[0..len] });
+                                    continue;
+                                }
                             },
                         };
                         this.postEvent(.{ .key = key });

src/event.zig

@@ -23,6 +23,8 @@ pub const SystemEvent = union(enum) {
         /// associated error message
         msg: []const u8,
     },
+    /// Input line event received in non *raw mode* (instead of individual `key` events)
+    line: []const u8,
     /// Input key event received from the user
     key: Key,
     /// Mouse input event

src/render.zig

@@ -144,8 +144,6 @@ pub const Direct = struct {
     }
 
     pub fn resize(this: *@This()) !Point {
-        // TODO the size in the y-axis is *not fixed* and *not limited*
-        // how can I achive this?
         this.size = .{};
         if (!this.resized) {
             this.gpa.free(this.screen);
@@ -160,7 +158,7 @@ pub const Direct = struct {
         try terminal.clearScreen();
     }
 
-    /// Render provided cells at size (anchor and dimension) into the *virtual screen*.
+    /// Render provided cells at size (anchor and dimension) into the *screen*.
     pub fn render(this: *@This(), comptime Container: type, container: *Container, comptime Model: type, model: *const Model) !void {
         const size: Point = container.size;
         const origin: Point = container.origin;
@@ -179,7 +177,6 @@ pub const Direct = struct {
         var vs = this.screen;
         const anchor: usize = (@as(usize, origin.y) * @as(usize, this.size.x)) + @as(usize, origin.x);
 
-
         blk: for (0..size.y) |row| {
             for (0..size.x) |col| {
                 vs[anchor + (row * this.size.x) + col] = cells[idx];
@@ -200,6 +197,7 @@ pub const Direct = struct {
                 const idx = (row * this.size.x) + col;
                 const cvs = this.screen[idx];
                 try cvs.value(&writer);
+                if (cvs.style.cursor) return; // that's where the cursor should be left!
             }
         }
     }

src/terminal.zig

@@ -98,7 +98,7 @@ pub fn setCursorPosition(pos: Point) !void {
     _ = try posix.write(posix.STDIN_FILENO, value);
 }
 
-pub fn getCursorPosition() !Size.Position {
+pub fn getCursorPosition() !Size {
     // Needs Raw mode (no wait for \n) to work properly cause
     // control sequence will not be written without it.
     _ = try posix.write(posix.STDIN_FILENO, "\x1b[6n");