declare ncplane_growtext()

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,

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

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

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