.\" Automatically generated by Pandoc 3.1.8
.\"
.TH "notcurses_stdplane" "3" "v3.0.9" "" ""
.SH NAME
notcurses_stdplane - acquire the standard ncplane
.SS SYNOPSIS
\f[B]#include <notcurses/notcurses.h>\f[R]
.PP
\f[B]struct ncplane* notcurses_stdplane(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]const struct ncplane* notcurses_stdplane_const(const struct
notcurses* \f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]static inline struct ncplane* notcurses_stddim_yx(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B], unsigned* restrict \f[R]\f[I]y\f[R]\f[B],
unsigned* restrict \f[R]\f[I]x\f[R]\f[B]);\f[R]
.PP
\f[B]static inline const struct ncplane* notcurses_stddim_yx_const(const
struct notcurses* \f[R]\f[I]nc\f[R]\f[B], unsigned* restrict
\f[R]\f[I]y\f[R]\f[B], unsigned* restrict \f[R]\f[I]x\f[R]\f[B]);\f[R]
.PP
\f[B]int notcurses_enter_alternate_screen(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]int notcurses_leave_alternate_screen(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.SH DESCRIPTION
\f[B]notcurses_stdplane\f[R] returns a handle to the standard ncplane
for the context \f[B]nc\f[R].
The standard plane always exists, and is always the same size as the
screen.
It is an error to call \f[B]ncplane_destroy(3)\f[R],
\f[B]ncplane_resize(3)\f[R], or \f[B]ncplane_move(3)\f[R] on the
standard plane, but it can be freely moved along the z-axis.
.PP
The standard plane\[aq]s virtual cursor is initialized to its uppermost,
leftmost cell unless \f[B]NCOPTION_PRESERVE_CURSOR\f[R] is provided (see
\f[B]notcurses_init(3)\f[R]), in which case it is placed wherever the
terminal\[aq]s real cursor was at startup.
.PP
\f[B]notcurses_stddim_yx\f[R] provides the same function, but also
writes the dimensions of the standard plane (and thus the real drawable
area) into any non-\f[B]NULL\f[R] parameters among \f[B]y\f[R] and
\f[B]x\f[R].
.PP
\f[B]notcurses_stdplane_const\f[R] allows a \f[B]const notcurses\f[R] to
be safely used.
.PP
A resize event does not invalidate these references.
They can be used until \f[B]notcurses_stop(3)\f[R] is called on the
associated \f[B]nc\f[R].
.PP
\f[B]notcurses_enter_alternate_screen\f[R] and
\f[B]notcurses_leave_alternate_screen\f[R] only have meaning if the
terminal implements the \[dq]alternate screen\[dq] via the
\f[B]smcup\f[R] and \f[B]rmcup\f[R] \f[B]terminfo(5)\f[R] capabilities
(see the discussion of \f[B]NCOPTION_NO_ALTERNATE_SCREEN\f[R] in
\f[B]notcurses_init(3)\f[R]).
If not currently using the alternate screen, and assuming it is
supported, \f[B]notcurses_enter_alternate_screen\f[R] 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.
.SH RETURN VALUES
\f[B]notcurses_enter_alternate_screen\f[R] will return -1 if the
alternate screen is unavailable.
Both it and \f[B]notcurses_leave_alternate_screen\f[R] will return -1 on
an I/O failure.
.PP
Other functions cannot fail when provided a valid \f[B]struct
notcurses\f[R].
They will always return a valid pointer to the standard plane.
.SH SEE ALSO
\f[B]notcurses(3)\f[R], \f[B]notcurses_init(3)\f[R],
\f[B]notcurses_plane(3)\f[R], \f[B]notcurses_stop(3)\f[R],
\f[B]terminfo(5)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.