blackbeard420/notcurses
1
0
Fork 0
mirror of https://github.com/dankamongmen/notcurses synced 2025-03-09 17:19:03 -04:00
Code Issues Projects Releases Wiki Activity

[notcurses.3] talk about the alternate screen

Browse Source
This commit is contained in:
nick black 2021-12-03 20:14:45 -05:00
parent 52c40cbca5
commit 64f514d7af
No known key found for this signature in database
GPG Key ID: 5F43400C21CBFACC
2 changed files with 28 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/man/man3/notcurses.3.md
View File

@ -30,6 +30,20 @@ to link against a minimal Notcurses using **pkg-config --libs notcurses-core**.
**notcurses_init(3)** can then be used to initialize a Notcurses instance for a
given **FILE*** (usually **stdout**, usually attached to a terminal).
## The alternate screen
Many terminals provide an "alternate screen" with its own contents, no
scrollback buffer, and no scrolling. Entering the alternate screen replaces
the current visible contents wholesale, as does returning to the regular
screen. Notcurses refers to the alternate screen's semantics as "TUI mode",
and the regular screen's semantics as "CLI mode". It is possible to swap
between the two modes at runtime using **notcurses_leave_alternate_screen(3)**
and **notcurses_enter_alternate_screen(3)**. Notcurses will enter TUI mode
by default on startup; to prevent this, use **NCOPTION_NO_ALTERNATE_SCREEN**
as described in **notcurses_init(3)**. On program exit, Notcurses will always
return to the regular screen, independent of the screen being used on
program start.
## Construction
Before calling into Notcurses—and usually as one of the first calls of the

28
doc/man/man3/notcurses_plane.3.md
View File

@ -355,6 +355,19 @@ are O(N) on the number of planes in the pile.
**ncplane_move_above** and **ncplane_move_below** move the argument ***n***
above or below, respectively, the argument ***targ***. Both operate in O(1).
**ncplane_at_yx** and **ncplane_at_yx_cell** retrieve the contents of the plane
at the specified coordinate. The content is returned as it will be used during
rendering, and thus integrates any base cell as appropriate. If called on the
secondary columns of a wide glyph, **ncplane_at_yx** returns the EGC, and thus
cannot be used to distinguish between primary and secondary columns.
**ncplane_at_yx_cell**, however, preserves this information: retrieving a
secondary column of a wide glyph with **ncplane_at_yx_cell** will fill in
the **nccell** argument such that **nccell_extended_gcluster(3)** returns an
empty string, and **nccell_wide_right_p(3)** returns **true**.
**ncplane_set_name** sets the plane's name, freeing any old name. ***name***
may be **NULL**. **ncplane_set_name** duplicates the provided name internally.
## Base cells
Each plane has a base cell, initialized to all zeroes. When rendering, the
@ -424,7 +437,7 @@ beginning of the last row. This does not take place until output is generated
(i.e. it is possible to fill a plane when scrolling is enabled).
By default, planes bound to a scrolling plane will scroll along with it, if
they intersect the plane. This can be disabled with the
they intersect the plane. This can be disabled by creating them with the
**NCPLANE_OPTION_FIXED** flag.
## Bitmaps
@ -442,19 +455,6 @@ is resized, the plane is erased, or the plane is destroyed. The base cell of a
sprixelated plane has no effect; if the sprixel is not even multiples of the
cell geometry, the "excess plane" is ignored during rendering.
**ncplane_at_yx** and **ncplane_at_yx_cell** retrieve the contents of the plane
at the specified coordinate. The content is returned as it will be used during
rendering, and thus integrates any base cell as appropriate. If called on the
secondary columns of a wide glyph, **ncplane_at_yx** returns the EGC, and thus
cannot be used to distinguish between primary and secondary columns.
**ncplane_at_yx_cell**, however, preserves this information: retrieving a
secondary column of a wide glyph with **ncplane_at_yx_cell** will fill in
the **nccell** argument such that **nccell_extended_gcluster(3)** returns an
empty string, and **nccell_wide_right_p(3)** returns **true**.
**ncplane_set_name** sets the plane's name, freeing any old name. ***name***
may be **NULL**.
# RETURN VALUES
**ncplane_create** and **ncplane_dup** return a new **struct ncplane** on