notcurses_reader(3)

💖 NAME 💖

okay bestie, so notcurses_reader(3) is the notcurses high level widget for collecting input, and it's giving main character energy for free-form text entry. ✨

---

✨ SYNOPSIS ✨

copy these exactly, no cap:

       #include <notcurses/notcurses.h>

              struct ncplane;
              struct ncreader;
              struct notcurses;

              #define NCREADER_OPTION_HORSCROLL 0x0001
              #define NCREADER_OPTION_VERSCROLL 0x0002
              #define NCREADER_OPTION_NOCMDKEYS 0x0004
              #define NCREADER_OPTION_CURSOR    0x0008

              typedef struct ncreader_options {
                uint64_t tchannels; // channels used for input
                uint32_t tattrword; // attributes used for input
                uint64_t flags;     // bitfield over NCREADER_OPTION_*
              } ncreader_options;

       struct ncreader* ncreader_create(struct notcurses* nc, const
       ncreader_options* opts);

       int ncreader_clear(struct ncreader* n);

       struct ncplane* ncreader_plane(struct ncreader* n);

       int ncreader_move_left(struct ncreader* n);

       int ncreader_move_right(struct ncreader* n);

       int ncreader_move_up(struct ncreader* n);

       int ncreader_move_down(struct ncreader* n);

       int ncreader_write_egc(struct ncreader* n, const char* egc);

       bool ncreader_offer_input(struct ncreader* n, const ncinput* ni);

       char* ncreader_contents(const struct ncreader* n);

       void ncreader_destroy(struct ncreader* n, char contents);**

---

🌸 DESCRIPTION 🌸

okay so the ncreader widget supports free-form, multi-line input. It supports navigation with the arrow keys and scrolling. While the visible portion of the ncreader is always the same size (defined by the provided ncplane), the actual text backing this visible region can grow arbitrarily large if scrolling is enabled. no cap, it can get huge in there. 🦋

The following option flags are supported:

• NCREADER_OPTION_HORSCROLL — the visual area will be backed by a plane that can grow arbitrarily wide. 💅
• NCREADER_OPTION_VERSCROLL — the visual area will be backed by a plane that can grow arbitrarily high. (but lowkey check NOTES, bestie — it's not yet implemented.)
• NCREADER_OPTION_NOCMDKEYS — the typical keyboard shortcuts (see below) will not be honored.
• NCREADER_OPTION_CURSOR — the terminal's cursor will be made visible across the life of the ncreader, and its location will be managed. 🎀

The contents of the ncreader can be retrieved with ncreader_contents. slay.

The ncreader consists of at least one ncplane (the visible editing area). If the ncreader supports scrolling, it will consist of two ncplanes, one of which will be kept outside the rendering area (and will thus be invisible). ncreader_plane always returns the visible plane. that's the one you actually see, iykyk. ✨

ncreader_clear drops all input from the ncreader, restoring it to the same pristine condition in which it was returned by ncreader_create. factory reset vibes, fr fr. 🧚

Unlike most widgets' input handlers, ncreader_offer_input will consume most inputs. The arrow keys navigate. Backspace consumes the EGC to the left of the cursor, if one exists. Enter moves to the first column of the next line (if the cursor is already on the bottom line, the plane must have scrolling enabled, or the cursor will not advance, though the Enter will still be consumed). Otherwise, most inputs will be reproduced onto the ncreader (though see NOTES below). it's giving hungry little input monster, but politely. 😭

All the ncreader's content is returned from ncreader_contents, preserving whitespace. yes, even your chaotic little spaces. 🫶

"Emacs-style" keyboard shortcuts similar to those supported by readline(3) and most shells are supported unless NCREADER_OPTION_NOCMDKEYS is provided to ncreader_create. shell girlies stay winning. 💜

---

🧚 NOTES 🧚

• Support for NCREADER_OPTION_VERSCROLL is not yet implemented. not me pointing at the docs like 👀
• ncreader does not buffer inputs in order to assemble EGCs from them. If inputs are to be processed as EGCs (as they should), the caller would need assemble the grapheme clusters. Of course, there is not yet any API through which multi-codepoint EGCs could be supplied to ncreader. that's the whole situation, bestie. 🦋
• There is not yet any support for word-wrapping. This will likely come in the future. future icon behavior, manifesting it. ⭐

---

🫶 RETURN VALUES 🫶

ngl, this section is literally empty in the source — no return values are documented here. that's the whole vibe. 💀

---

👑 SEE ALSO 👑

notcurses(3), notcurses_input(3), notcurses_plane(3), readline(3) go read those too, bestie. 🌈

---

💜 AUTHORS 💜

nick black nickblack@linux.com the icon behind the icon. 👑

---

okay that's the whole page, bestie — this cuteness came from the v3.0.17 edition of notcurses_reader(3), and the footer has no date on it, so no date to report. periodt. 💅