.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_refresh" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_refresh - redraw an externally-damaged display
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.PP
\f[B]int notcurses_refresh(const struct notcurses*
\f[R]\f[I]nc\f[R]\f[B], int* restrict \f[R]\f[I]rows\f[R]\f[B], int*
restrict \f[R]\f[I]cols\f[R]\f[B]);\f[R]
.SH DESCRIPTION
.PP
\f[B]notcurses_refresh\f[R] clears the screen, homes the cursor, checks
the current terminal geometry, and repaints the most recently rendered
frame.
It can be called concurrently with all other Notcurses functions save
\f[B]notcurses_render\f[R].
\f[B]notcurses_refresh\f[R] ought be called when the screen is
externally damaged (as occurs when another program writes to the
terminal, or if your program writes to the terminal using standard I/O).
It is necessary to use \f[B]notcurses_refresh\f[R] in such a case (as
opposed to simply calling \f[B]notcurses_render\f[R]), since
\f[B]notcurses_render\f[R] optimizes its output by only writing
internally-damaged cells.
Notcurses has no way of knowing about external corruption; by tradition,
Ctrl+L is bound to \f[B]notcurses_refresh\f[R], and the user is
responsible for requesting a hard redraw.
.PP
A secondary use of this function is when the program is blocking on
input (and perhaps not ready to render), and receives an
\f[B]NCKEY_RESIZE\f[R] event (see \f[B]notcurses_input\f[R]).
In this case, \f[B]notcurses_refresh\f[R] will acquire the new screen
parameters, and repaint what it can.
If you\[cq]re prepared to call \f[B]notcurses_render\f[R], it\[cq]s
better to do that in this case, and thus avoid unnecessary screen
redrawing.
.PP
If \f[B]rows\f[R] and/or \f[B]cols\f[R] is not NULL, they receive the
new geometry.
.SH NOTES
.PP
If your program \f[B]is\f[R] in a render loop (i.e.\ rendering as
quickly as possible, or at least at the refresh rate), there\[cq]s not
much point in erecting the machinery to trigger
\f[B]notcurses_refresh\f[R] based off \f[B]NCKEY_RESIZE\f[R].
The latter is generated based upon receipt of the \f[B]SIGWINCH\f[R]
signal, which is fundamentally racy with regards to the rest of the
program.
If your program truly relies on timely invocation of
\f[B]notcurses_refresh\f[R], it\[cq]s a broken program.
If you don\[cq]t rely on it in a causal fashion, then just wait for the
upcoming render.
.PP
Highest performance in a rendering loop would actually call for
disabling Notcurses\[cq]s \f[B]SIGWINCH\f[R] handling in the call to
\f[B]notcurses_init\f[R], so that no time is spent handling a signal
you\[cq]re not going to use.
.SH RETURN VALUES
.PP
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 \f[B]notcurses_refresh\f[R] failure is either to ignore
it, or to weep and exit.
.SH SEE ALSO
.PP
\f[B]notcurses_init(3)\f[R], \f[B]notcurses_input(3)\f[R],
\f[B]notcurses_render(3)\f[R], \f[B]termios(3)\f[R], \f[B]signal(7)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.