From b7785d127273f1fa05c999fe7e95f32e7faa1cd5 Mon Sep 17 00:00:00 2001 From: nick black Date: Mon, 6 Dec 2021 22:20:11 -0500 Subject: [PATCH] declare ncplane_growtext() --- NEWS.md | 4 ++++ USAGE.md | 8 ++++++++ doc/man/man3/notcurses_output.3.md | 3 +++ include/notcurses/notcurses.h | 9 +++++++++ 4 files changed, 24 insertions(+) diff --git a/NEWS.md b/NEWS.md index aa7991733..a999277fa 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,10 @@ This document attempts to list user-visible changes and any major internal rearrangements of Notcurses. +* 3.0.1 (not yet released) + * Added `ncplane_growtext()`, which allows you to dump text to a plane + (ala `ncplane_puttext()`), and have it grow right along with you. + * 3.0.0 (2021-12-01) **"In the A"** * Made the ABI/API changes that have been planned/collected during 2.x development. This primarily involved removing deprecated functions, diff --git a/USAGE.md b/USAGE.md index 19c9c8c4d..a34da695d 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1456,6 +1456,14 @@ of [Unicode Annex #14](http://www.unicode.org/reports/tr14/tr14-34.html). // determine whether the write completed by inspecting '*bytes'. int ncplane_puttext(struct ncplane* n, int y, ncalign_e align, const char* text, size_t* bytes); + +// Like ncplane_puttext(), we're going for an orderly presentation of (possibly +// bulk) text. Unlike ncplane_puttext(), we're going to grow the plane as +// necessary to present it. If the plane is scrolling, we'll grow the bottom +// out; we'll otherwise grow out to the right. Either way, no actual scrolling +// will occur. +int ncplane_growtext(struct ncplane* n, int y, ncalign_e align, + const char* text, size_t* bytes); ``` Lines and boxes can be drawn, interpolating their colors between their two diff --git a/doc/man/man3/notcurses_output.3.md b/doc/man/man3/notcurses_output.3.md index 42a616947..26abf43b7 100644 --- a/doc/man/man3/notcurses_output.3.md +++ b/doc/man/man3/notcurses_output.3.md @@ -76,6 +76,8 @@ notcurses_output - output to ncplanes **int ncplane_puttext(struct ncplane* ***n***, int ***y***, ncalign_e ***align***, const char* ***text***, size_t* ***bytes***);** +**int ncplane_growtext(struct ncplane* ***n***, int ***y***, ncalign_e ***align***, const char* ***text***, size_t* ***bytes***);** + # DESCRIPTION These functions write EGCs (Extended Grapheme Clusters) to the specified @@ -91,6 +93,7 @@ These functions write EGCs (Extended Grapheme Clusters) to the specified * **ncplane_vprintf()**: formatted output using **va_list** * **ncplane_printf()**: formatted output using variadic arguments * **ncplane_puttext()**: multi-line, line-broken, aligned text +* **ncplane_growtext()**: **ncplane_growtext()** with an autogrowing plane All of these use the **ncplane**'s active styling, save **notcurses_putc()**, which uses the **nccell**'s styling. Functions accepting a single EGC expect a series diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index 3d145b7f6..af902bdf6 100644 --- a/include/notcurses/notcurses.h +++ b/include/notcurses/notcurses.h @@ -2359,6 +2359,15 @@ API int ncplane_puttext(struct ncplane* n, int y, ncalign_e align, const char* text, size_t* bytes) __attribute__ ((nonnull (1, 4))); +// Like ncplane_puttext(), we're going for an orderly presentation of (possibly +// bulk) text. Unlike ncplane_puttext(), we're going to grow the plane as +// necessary to present it. If the plane is scrolling, we'll grow the bottom +// out; we'll otherwise grow out to the right. Either way, no actual scrolling +// will occur. +API int ncplane_growtext(struct ncplane* n, int y, ncalign_e align, + const char* text, size_t* bytes) + __attribute__ ((nonnull (1, 4))); + // Draw horizontal or vertical lines using the specified cell, starting at the // current cursor position. The cursor will end at the cell following the last // cell output (even, perhaps counter-intuitively, when drawing vertical