2.7 KiB
% notcurses_resize(3) % nick black nickblack@linux.com % v1.2.1
NAME
notcurses_resize - resizeialize a notcurses instance
SYNOPSIS
#include <notcurses.h>
int notcurses_resize(const struct notcurses nc, int rows, int* cols);**
DESCRIPTION
notcurses_resize causes notcurses to retrieve the screen's current size using termios(3). If it has changed, notcurses will resize the standard plane appropriately. Like any other ncplane_resize(3) operation, lost space will be culled from the standard plane, while new space will be populated by the standard plane's base cell. Other planes are unaffected. notcurses_resize does not result in a rendering operation.
notcurses_render(3) calls this function following a render+raster cycle. It is thus not necessary to call it yourself unless both of the following are true:
- Your program is in an event loop rather than a rendering loop (i.e. it calls notcurses_render(3) only based on external events), and
- Your program makes use of the standard plane, or the standard plane's dimensions.
If this is the case, you might call notcurses_resize based on an NCKEY_RESIZE event on the input channel (see notcurses_input(3)), so that you can write to the standard plane using its new size prior to a render. If you have no changes, and just want to render what you have (with more or less now visible), it is sufficient to simply call notcurses_render(3).
If rows and/or cols is not NULL, they receive the new geometry.
NOTES
If your program is in a render loop (i.e. rendering as quickly as possible, or at least at the refresh rate), there's not much point in erecting the machinery to trigger notcurses_resize based off NCKEY_RESIZE. The latter is generated based upon receipt of the SIGWINCH signal, which is fundamentally racy with regards to the rest of the program. If your program truly relies on timely invocation of notcurses_resize(), it's a broken program. If you don't rely on it in a causal fashion, then just wait for the upcoming render.
Highest performance in a rendering loop would actually call for disabling notcurses SIGWINCH handling in the call to notcurses_init(3), so that no time is spent handling a signal you're not going to use.
RETURN VALUES
Returns 0 on success, and -1 on failure. The causes for failure include system error, programming error, closing of output, or allocation failure. None of these are particularly good things, and the most reasonable response to a notcurses_resize failure is probably to weep.
SEE ALSO
notcurses_init(3), notcurses_input(3), notcurses_ncplane(3), notcurses_render(3), termios(3), signal(7)