NAME

       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*  re‐
       strict y, unsigned* restrict x);

       int notcurses_enter_alternate_screen(struct notcurses* nc);

       int notcurses_leave_alternate_screen(struct notcurses* nc);

DESCRIPTION

       notcurses_stdplane  returns  a handle to the standard ncplane for the context nc.  The standard plane al‐
       ways exists, and is always the same size as the screen.  It is an error to call  ncplane_destroy(3),  nc‐
       plane_resize(3), or ncplane_move(3) on the standard plane, but it can be freely moved along the z-axis.

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

       notcurses_stddim_yx provides the same function, but 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 as‐
       suming it is supported, notcurses_enter_alternate_screen will switch to the alternate screen.   This  re‐
       draws 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.

SEE ALSO

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

AUTHORS

       nick black <nickblack@linux.com>.

                                                     v3.0.7                                notcurses_stdplane(3)