notcurses/doc/man/man3/notcurses_stdplane.3.md

73 lines
2.8 KiB
Markdown
Raw Normal View History

2020-01-02 02:23:11 +00:00
% notcurses_stdplane(3)
% nick black <nickblack@linux.com>
2021-10-23 10:36:18 +00:00
% v2.4.8
2020-01-02 02:23:11 +00:00
# NAME
notcurses_stdplane - acquire the standard ncplane
2020-01-02 02:23:11 +00:00
## SYNOPSIS
**#include <notcurses/notcurses.h>**
2020-01-02 02:23:11 +00:00
**struct ncplane* notcurses_stdplane(struct notcurses* ***nc***);**
2020-01-02 02:23:11 +00:00
**const struct ncplane* notcurses_stdplane_const(const struct notcurses* ***nc***);**
2021-11-07 02:32:20 +00:00
**static inline struct ncplane* notcurses_stddim_yx(struct notcurses* ***nc***, unsigned* restrict ***y***, unsigned* restrict ***x***);**
2020-10-19 05:37:31 +00:00
2021-11-07 02:32:20 +00:00
**static inline const struct ncplane* notcurses_stddim_yx_const(const struct notcurses* ***nc***, unsigned* restrict ***y***, unsigned* restrict ***x***);**
2020-02-21 04:40:13 +00:00
**int notcurses_enter_alternate_screen(struct notcurses* ***nc***);**
**int notcurses_leave_alternate_screen(struct notcurses* ***nc***);**
2020-01-02 02:23:11 +00:00
# DESCRIPTION
**notcurses_stdplane** returns a handle to the standard ncplane for the context
**nc**. The standard plane always exists, and is always the same size as the
screen. It is an error to call **ncplane_destroy(3)**, **ncplane_resize(3)**,
2020-02-21 05:13:47 +00:00
or **ncplane_move(3)** on the standard plane, but it can be freely moved
2020-01-02 02:23:11 +00:00
along the z-axis.
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 is placed wherever the terminal's
real cursor was at startup.
2020-02-21 04:40:13 +00:00
**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.
2020-02-21 04:40:13 +00:00
A resize event does not invalidate these references. They can be used until
**notcurses_stop(3)** is called on the associated **nc**.
2020-01-02 02:23:11 +00:00
**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.
2020-01-02 02:23:11 +00:00
# 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
2020-01-02 02:23:11 +00:00
will always return a valid pointer to the standard plane.
# SEE ALSO
2020-02-21 04:40:13 +00:00
**notcurses(3)**,
**notcurses_init(3)**,
**notcurses_plane(3)**,
**notcurses_stop(3)**,
**terminfo(5)**