NCOPTION_SCROLLING, alias NCOPTION_CLI_MODE

CMakeLists.txt

@@ -814,6 +814,12 @@ add_test(
   COMMAND rgbbg
 )
 LIST(APPEND TESTBINS notcurses-info sgr-direct sgr-full rgb rgbbg)
+if(${USE_QRCODEGEN})
+add_test(
+  NAME qrcode
+  COMMAND qrcode
+)
+endif()
 set_tests_properties(
   ${TESTBINS} PROPERTIES RUN_SERIAL TRUE
 )

NEWS.md

@@ -3,6 +3,11 @@ rearrangements of Notcurses.
 
 * 3.0.2 (2021-12-21)
   * Added `ncplane_cursor_y()` and `ncplane_cursor_x()`.
+  * Added `NCOPTION_SCROLLING`, equivalent to calling
+    `ncplane_set_scrolling(true)` on the standard plane.
+  * Added `NCOPTION_CLI_MODE`, an alias for the bitwise OR of
+    `NCOPTION_SCROLLING`, `NCOPTION_NO_CLEAR_BITMAPS`,
+    `NCOPTION_NO_ALTERNATE_SCREEN`, and `NCOPTION_PRESERVE_CURSOR`.
 
 * 3.0.1 (2021-12-14)
   * Added the `NCPLANE_OPTION_VSCROLL` flag. Creating an `ncplane` with this

USAGE.md

@@ -131,6 +131,16 @@ typedef enum {
 // eventually preventing Notcurses from processing terminal messages.
 #define NCOPTION_DRAIN_INPUT         0x0100
 
+// Prepare the standard plane in scrolling mode, useful for CLIs. This is
+// equivalent to calling ncplane_set_scrolling(notcurses_stdplane(nc), true).
+#define NCOPTION_SCROLLING           0x0200ull
+
+// "CLI mode" is just setting these four options.
+#define NCOPTION_CLI_MODE (NCOPTION_NO_ALTERNATE_SCREEN \
+                           |NCOPTION_NO_CLEAR_BITMAPS \
+                           |NCOPTION_PRESERVE_CURSOR \
+                           |NCOPTION_SCROLLING)
+
 // Configuration for notcurses_init().
 typedef struct notcurses_options {
   // The name of the terminfo database entry describing this terminal. If NULL,

doc/man/man3/notcurses_init.3.md

@@ -20,6 +20,12 @@ notcurses_init - initialize a Notcurses instance
 #define NCOPTION_NO_ALTERNATE_SCREEN 0x0040ull
 #define NCOPTION_NO_FONT_CHANGES     0x0080ull
 #define NCOPTION_DRAIN_INPUT         0x0100ull
+#define NCOPTION_SCROLLING           0x0200ull
+
+#define NCOPTION_CLI_MODE (NCOPTION_NO_ALTERNATE_SCREEN \
+                           |NCOPTION_NO_CLEAR_BITMAPS \
+                           |NCOPTION_PRESERVE_CURSOR \
+                           |NCOPTION_SCROLLING)
 
 typedef enum {
   NCLOGLEVEL_SILENT,  // print nothing once fullscreen service begins
@@ -170,6 +176,16 @@ zero. The following flags are defined:
     eventually prevent Notcurses from processing messages from the terminal. It
     will furthermore avoid wasting time processing useless input.
 
+* **NCOPTION_SCROLLING**: Enable scrolling on the standard plane. This is
+    equivalent to calling **ncplane_set_scrolling(stdn, true)** on some
+    standard plane ***stdn***.
+
+**NCOPTION_CLI_MODE** is provided as an alias for the bitwise OR of
+**NCOPTION_SCROLLING**, **NCOPTION_NO_ALTERNATE_SCREEN**,
+**NCOPTION_PRESERVE_CURSOR**, and **NCOPTION_NO_CLEAR_BITMAPS**. If
+writing a CLI, it is recommended to use **NCOPTION_CLI_MODE** rather
+than explicitly listing these options.
+
 **notcurses_default_foreground** returns the default foreground color, if it
 could be detected. **notcurses_default_background** returns the default
 background color, if it could be detected.

include/notcurses/notcurses.h

@@ -964,8 +964,15 @@ typedef enum {
 // eventually preventing Notcurses from processing terminal messages.
 #define NCOPTION_DRAIN_INPUT         0x0100ull
 
-// "CLI mode" is just NCOPTION_NO_CLEAR_BITMAPS | NCOPTION_NO_ALTERNATE_SCREEN |
-// NCOPTION_PRESERVE_CURSOR, plus enabling scrolling on the standard plane.
+// Prepare the standard plane in scrolling mode, useful for CLIs. This is
+// equivalent to calling ncplane_set_scrolling(notcurses_stdplane(nc), true).
+#define NCOPTION_SCROLLING           0x0200ull
+
+// "CLI mode" is just setting these four options.
+#define NCOPTION_CLI_MODE (NCOPTION_NO_ALTERNATE_SCREEN \
+                           |NCOPTION_NO_CLEAR_BITMAPS \
+                           |NCOPTION_PRESERVE_CURSOR \
+                           |NCOPTION_SCROLLING)
 
 // Configuration for notcurses_init().
 typedef struct notcurses_options {

src/demo/demo.c

@@ -122,17 +122,14 @@ static void
 usage(const char* exe, int status){
   FILE* out = status == EXIT_SUCCESS ? stdout : stderr;
   struct notcurses_options opts = {0};
-  opts.flags = NCOPTION_NO_ALTERNATE_SCREEN
+  opts.flags = NCOPTION_CLI_MODE
                | NCOPTION_DRAIN_INPUT
-               | NCOPTION_NO_CLEAR_BITMAPS
-               | NCOPTION_PRESERVE_CURSOR
                | NCOPTION_SUPPRESS_BANNERS;
   struct notcurses* nc = notcurses_init(&opts, out);
   if(!nc){
     exit(status);
   }
   struct ncplane* n = notcurses_stdplane(nc);
-  ncplane_set_scrolling(n, true);
   ncplane_set_fg_rgb8(n, 0x00, 0xc0, 0xc0);
   ncplane_putstr(n, "usage: ");
   ncplane_set_fg_rgb8(n, 0x80, 0xff, 0x80);

src/lib/notcurses.c

@@ -1140,7 +1140,7 @@ notcurses_early_init(const struct notcurses_options* opts, FILE* fp, unsigned* u
   }
   memset(ret, 0, sizeof(*ret));
   if(opts){
-    if(opts->flags >= (NCOPTION_DRAIN_INPUT << 1u)){
+    if(opts->flags >= (NCOPTION_SCROLLING << 1u)){
       fprintf(stderr, "warning: unknown Notcurses options %016" PRIu64, opts->flags);
     }
     if(opts->termtype){
@@ -1287,6 +1287,9 @@ notcurses* notcurses_core_init(const notcurses_options* opts, FILE* outfp){
     logpanic("couldn't create the initial plane (bad margins?)");
     goto err;
   }
+  if(ret->flags & NCOPTION_SCROLLING){
+    ncplane_set_scrolling(ret->stdplane, true);
+  }
   reset_term_attributes(&ret->tcache, &ret->rstate.f);
   const char* cinvis = get_escape(&ret->tcache, ESCAPE_CIVIS);
   if(cinvis && fbuf_emit(&ret->rstate.f, cinvis) < 0){

src/ls/main.cpp

@@ -310,9 +310,7 @@ int main(int argc, char* const * argv){
   }
   std::vector<std::thread> threads;
   struct notcurses_options nopts{};
-  nopts.flags |= NCOPTION_PRESERVE_CURSOR
-                | NCOPTION_NO_ALTERNATE_SCREEN
-                | NCOPTION_NO_CLEAR_BITMAPS
+  nopts.flags |= NCOPTION_CLI_MODE
                 | NCOPTION_SUPPRESS_BANNERS
                 | NCOPTION_DRAIN_INPUT;
   lsContext ctx = {
@@ -329,7 +327,6 @@ int main(int argc, char* const * argv){
   if((ctx.nc = notcurses_init(&nopts, nullptr)) == nullptr){
     return EXIT_FAILURE;
   }
-  ncplane_set_scrolling(notcurses_stdplane(ctx.nc), true);
   keep_working = true;
   for(auto s = 0u ; s < procs ; ++s){
     threads.emplace_back(std::thread(ncls_thread, &ctx));

src/poc/cjkscroll.c

@@ -6,9 +6,8 @@ int main(void){
   setlocale(LC_ALL, "");
   notcurses_options nopts = {
     .flags = NCOPTION_INHIBIT_SETLOCALE
-             | NCOPTION_NO_ALTERNATE_SCREEN
-             | NCOPTION_DRAIN_INPUT
-             | NCOPTION_PRESERVE_CURSOR,
+             | NCOPTION_CLI_MODE
+             | NCOPTION_DRAIN_INPUT,
   };
   struct notcurses* nc = notcurses_core_init(&nopts, NULL);
   if(nc == NULL){
@@ -17,7 +16,6 @@ int main(void){
   unsigned dimy, dimx;
   struct ncplane* n = notcurses_stddim_yx(nc, &dimy, &dimx);
   wchar_t wc = 0x4e00;
-  ncplane_set_scrolling(n, true);
   ncplane_set_styles(n, NCSTYLE_BOLD);
   ncplane_putstr(n, "This program is *not* indicative of real scrolling speed.\n");
   ncplane_set_styles(n, NCSTYLE_NONE);

src/poc/cli1.c

@@ -5,16 +5,13 @@
 
 int main(void){
   struct notcurses_options nopts = {
-    .flags = NCOPTION_PRESERVE_CURSOR |
-             NCOPTION_NO_CLEAR_BITMAPS |
-             NCOPTION_NO_ALTERNATE_SCREEN,
+    .flags = NCOPTION_CLI_MODE,
   };
   struct notcurses* nc = notcurses_init(&nopts, NULL);
   if(nc == NULL){
     return EXIT_FAILURE;
   }
   struct ncplane* stdn = notcurses_stdplane(nc);
-  ncplane_set_scrolling(stdn, true);
   ncinput ni;
   do{
     if(ncplane_putstr(stdn, "press any key, q to quit\n") < 0){

src/poc/cli2.c

@@ -2,9 +2,7 @@
 
 int main(void){
   struct notcurses_options opts = {
-    .flags = NCOPTION_NO_ALTERNATE_SCREEN |
-             NCOPTION_PRESERVE_CURSOR |
-             NCOPTION_NO_CLEAR_BITMAPS |
+    .flags = NCOPTION_CLI_MODE |
              NCOPTION_DRAIN_INPUT,
   };
   struct notcurses* nc = notcurses_init(&opts, NULL);

src/poc/cli3.c

@@ -1,6 +1,7 @@
 #include <notcurses/notcurses.h>
 
 int main(void){
+  // explicitly want alternate screen, so no NCOPTION_CLI_MODE
   struct notcurses_options opts = {
     .flags = NCOPTION_PRESERVE_CURSOR |
              NCOPTION_NO_CLEAR_BITMAPS |

src/poc/fbconscroll.c

@@ -14,11 +14,9 @@ int main(int argc, char** argv){
     }
   }
   struct notcurses_options nopts = {
-    .flags = NCOPTION_NO_ALTERNATE_SCREEN
-             | NCOPTION_NO_CLEAR_BITMAPS
+    .flags = NCOPTION_CLI_MODE
              | NCOPTION_SUPPRESS_BANNERS
              | NCOPTION_NO_FONT_CHANGES
-             | NCOPTION_PRESERVE_CURSOR
              | NCOPTION_DRAIN_INPUT,
   };
   struct notcurses* nc = notcurses_init(&nopts, NULL);
@@ -27,7 +25,6 @@ int main(int argc, char** argv){
   }
   unsigned dimy, dimx;
   struct ncplane* n = notcurses_stddim_yx(nc, &dimy, &dimx);
-  ncplane_set_scrolling(n, true);
   for(int i = 0 ; i < rows ; ++i){
     int r;
     if((r = ncplane_putchar(n, '\n')) != 0){

src/poc/grid.c

@@ -63,11 +63,9 @@ draw_grid(struct ncplane* stdn){
 
 int main(void){
   struct notcurses_options opts = {
-    .flags = NCOPTION_NO_ALTERNATE_SCREEN |
-             NCOPTION_DRAIN_INPUT |
-             NCOPTION_NO_CLEAR_BITMAPS |
+    .flags = NCOPTION_CLI_MODE |
              NCOPTION_SUPPRESS_BANNERS |
-             NCOPTION_PRESERVE_CURSOR,
+             NCOPTION_DRAIN_INPUT,
   //  .loglevel = NCLOGLEVEL_TRACE,
   };
   struct notcurses* nc = notcurses_init(&opts, NULL);

src/poc/procroller.c

@@ -44,7 +44,8 @@ int main(int argc, char** argv){
   setlocale(LC_ALL, "");
   notcurses_options opts = {
     .flags = NCOPTION_INHIBIT_SETLOCALE
-              | NCOPTION_SUPPRESS_BANNERS,
+              | NCOPTION_SUPPRESS_BANNERS
+              | NCOPTION_DRAIN_INPUT,
   };
   struct notcurses* nc = notcurses_core_init(&opts, NULL);
   if(nc == NULL){

src/poc/scroll.c

@@ -6,8 +6,7 @@ int main(void){
   setlocale(LC_ALL, "");
   struct notcurses_options opts = {
     .flags = NCOPTION_INHIBIT_SETLOCALE
-              | NCOPTION_NO_ALTERNATE_SCREEN
-              | NCOPTION_PRESERVE_CURSOR
+              | NCOPTION_CLI_MODE
               | NCOPTION_DRAIN_INPUT,
   };
   struct notcurses* nc = notcurses_core_init(&opts, NULL);
@@ -17,7 +16,6 @@ int main(void){
   unsigned dimy, dimx;
   struct ncplane* n = notcurses_stddim_yx(nc, &dimy, &dimx);
   char c = 'A';
-  ncplane_set_scrolling(n, true);
   ncplane_set_styles(n, NCSTYLE_BOLD);
   ncplane_putstr(n, "This program is *not* indicative of real scrolling speed.\n");
   ncplane_set_styles(n, NCSTYLE_NONE);

src/poc/sgr-full.c

@@ -4,9 +4,8 @@
 
 int main(void){
   struct notcurses_options nopts = {
-    .flags = NCOPTION_NO_ALTERNATE_SCREEN
+    .flags = NCOPTION_CLI_MODE
              | NCOPTION_SUPPRESS_BANNERS
-             | NCOPTION_PRESERVE_CURSOR
              | NCOPTION_DRAIN_INPUT,
   };
   struct notcurses* nc = notcurses_core_init(&nopts, NULL);
@@ -15,7 +14,6 @@ int main(void){
   }
   unsigned dimy, dimx;
   struct ncplane* n = notcurses_stddim_yx(nc, &dimy, &dimx);
-  ncplane_set_scrolling(n, true);
   // FIXME do full permutations?
   ncplane_set_styles(n, NCSTYLE_NONE);
   ncplane_putstr(n, "a ═ none\n");