add NCPLANE_OPTION_FIXED #1909

NEWS.md

@@ -1,6 +1,13 @@
 This document attempts to list user-visible changes and any major internal
 rearrangements of Notcurses.
 
+* 2.3.11 (not yet released)
+  * Notcurses now requires libz to build. In exchange, it can now generate
+    PNGs on the fly, necessary for driving iTerm2's graphics protocol.
+  * Added `NCPLANE_OPTION_FIXED`, to prevent a plane bound to a scrolling
+    plane from scrolling along with it.
+  * Added `input_errors` and `input_events` stats.
+
 * 2.3.10 (2021-07-14)
   * Notcurses now builds and works, so far as I can tell, on OS X 11.4+.
   * Emit XTPUSHCOLORS and XTPOPCOLORS where supported (XTerm and Kitty).

USAGE.md

@@ -774,6 +774,10 @@ When an `ncplane` is no longer needed, free it with
 // when this flag is used. 'rows' and 'cols' must be 0 when this flag is
 // used. This flag is exclusive with both of the alignment flags.
 #define NCPLANE_OPTION_MARGINALIZED 0x0004ull
+// If this plane is bound to a scrolling plane, it ought *not* scroll along
+// with the parent (it will still move with the parent, maintaining its
+// relative position, if the parent is moved to a new location).
+#define NCPLANE_OPTION_FIXED      0x0008ull
 
 typedef struct ncplane_options {
   int y;            // vertical placement relative to parent plane

doc/man/man3/notcurses_plane.3.md

@@ -14,6 +14,7 @@ notcurses_plane - operations on ncplanes
 #define NCPLANE_OPTION_HORALIGNED   0x0001ull
 #define NCPLANE_OPTION_VERALIGNED   0x0002ull
 #define NCPLANE_OPTION_MARGINALIZED 0x0004ull
+#define NCPLANE_OPTION_FIXED        0x0008ull
 
 typedef struct ncplane_options {
   int y;            // vertical placement relative to parent plane
@@ -374,13 +375,16 @@ at location 0x10; it must be moved before further printing can take place. If
 scrolling is enabled, the first row will be filled with 01234546789, the second
 row will have 0 written to its first column, and the cursor will end up at 1x1.
 Note that it is still an error to manually attempt to move the cursor
-off-plane, or to specify off-plane output. Boxes do not scroll; attempting to
+off-plane, or to specify off-plane output. Box-drawing does not result in
-draw a 2x11 box on our 2x10 plane will result in an error and no output. When
+scrolling; attempting to draw a 2x11 box on our 2x10 plane will result in an
-scrolling is enabled, and output takes place while the cursor is past the end
+error and no output. When scrolling is enabled, and output takes place while
-of the last row, the first row is discarded, all other rows are moved up, the
+the cursor is past the end of the last row, the first row is discarded, all
-last row is cleared, and output begins at the beginning of the last row. This
+other rows are moved up, the last row is cleared, and output begins at the
-does not take place until output is generated (i.e. it is possible to fill a
+beginning of the last row. This does not take place until output is generated
-plane when scrolling is enabled).
+(i.e. it is possible to fill a plane when scrolling is enabled).
+
+By default, planes bound to a scrolling plane will scroll along with it. This
+can be disabled with the **NCPLANE_OPTION_FIXED** flag.
 
 ## Bitmaps
 

include/notcurses/notcurses.h

@@ -1182,6 +1182,10 @@ API char* notcurses_at_yx(struct notcurses* nc, int yoff, int xoff,
 // when this flag is used. 'rows' and 'cols' must be 0 when this flag is
 // used. This flag is exclusive with both of the alignment flags.
 #define NCPLANE_OPTION_MARGINALIZED 0x0004ull
+// If this plane is bound to a scrolling plane, it ought *not* scroll along
+// with the parent (it will still move with the parent, maintaining its
+// relative position, if the parent is moved to a new location).
+#define NCPLANE_OPTION_FIXED      0x0008ull
 
 typedef struct ncplane_options {
   int y;            // vertical placement relative to parent plane