notcurses_stdplane(3)

💖 NAME 💖

okay bestie, welcome to notcurses_stdplane(3) — the page where we acquire the standard ncplane 👑

notcurses_stdplane — acquire the standard ncplane ✨

---

✨ SYNOPSIS ✨

#include <notcurses/notcurses.h>

struct ncplane* notcurses_stdplane(struct notcurses* nc);

const struct ncplane* notcurses_stdplane_const(const struct notcurses*
nc);

static inline struct ncplane* notcurses_stddim_yx(struct notcurses* nc,
unsigned* restrict y, unsigned* restrict x);

static inline const struct ncplane* notcurses_stddim_yx_const(const
struct notcurses* nc, unsigned* restrict y, unsigned* restrict x);

int notcurses_enter_alternate_screen(struct notcurses* nc);

int notcurses_leave_alternate_screen(struct notcurses* nc);

---

💖 DESCRIPTION 💖

okay so notcurses_stdplane hands you a handle to the standard ncplane for the context nc. The standard plane always exists, and it's always the same size as the screen. like, literally always 💅

bestie, it is an error to call ncplane_destroy(3), ncplane_resize(3), or ncplane_move(3) on the standard plane 🚫 but you can freely move it along the z-axis. slay.

The standard plane's virtual cursor is initialized to its uppermost, leftmost cell — unless NCOPTION_PRESERVE_CURSOR is provided (see notcurses_init(3)), in which case it's placed wherever the terminal's real cursor was at startup. 👀

notcurses_stddim_yx provides the same function, but it also writes the dimensions of the standard plane (and thus the real drawable area) into any non-NULL parameters among y and x. 🎀

notcurses_stdplane_const allows a const notcurses to be safely used. 💜

A resize event does not invalidate these references. They can be used until notcurses_stop(3) is called on the associated nc. 🦋

notcurses_enter_alternate_screen and notcurses_leave_alternate_screen only have meaning if the terminal implements the "alternate screen" via the smcup and rmcup terminfo(5) capabilities (see the discussion of NCOPTION_NO_ALTERNATE_SCREEN in notcurses_init(3)). If not currently using the alternate screen, and assuming it is supported, notcurses_enter_alternate_screen will switch to the alternate screen. This redraws the contents, repositions the cursor, and usually makes scrollback unavailable. The standard plane will have scrolling disabled upon a move to the alternate plane. 😭

---

🫶 RETURN VALUES 🫶

notcurses_enter_alternate_screen will return -1 if the alternate screen is unavailable. Both it and notcurses_leave_alternate_screen will return -1 on an I/O failure. 💀

Other functions cannot fail when provided a valid struct notcurses. They will always return a valid pointer to the standard plane. periodt ✨

---

👀 SEE ALSO 👀

• notcurses(3)
• notcurses_init(3)
• notcurses_plane(3)
• notcurses_stop(3)
• terminfo(5)

---

🎀 AUTHORS 🎀

nick black nickblack@linux.com 👑

---

✨ cute sign-off: this page is riding with notcurses v3.0.17, and the footer didn't give me a date, so there's no date to spill. byeeee 💅🫶