1notcurses_refresh(3) notcurses_refresh(3)
2
6 notcurses_refresh - redraw an externally-damaged display
7
9 #include <notcurses/notcurses.h>
10 int notcurses_refresh(const struct notcurses* nc, int* restrict rows,
12 int* restrict cols);
13
15 notcurses_refresh clears the screen, homes the cursor, checks the cur‐
16 rent terminal geometry, and repaints the most recently rendered frame.
17 It can be called concurrently with all other Notcurses functions save
18 notcurses_render. notcurses_refresh ought be called when the screen is
19 externally damaged (as occurs when another program writes to the termi‐
20 nal, or if your program writes to the terminal using standard I/O). It
21 is necessary to use notcurses_refresh in such a case (as opposed to
22 simply calling notcurses_render), since notcurses_render optimizes its
23 output by only writing internally-damaged cells. Notcurses has no way
24 of knowing about external corruption; by tradition, Ctrl+L is bound to
25 notcurses_refresh, and the user is responsible for requesting a hard
26 redraw.
27 A secondary use of this function is when the program is blocking on in‐
29 put (and perhaps not ready to render), and receives an NCKEY_RESIZE
30 event (see notcurses_input). In this case, notcurses_refresh will ac‐
31 quire the new screen parameters, and repaint what it can. If you're
32 prepared to call notcurses_render, it's better to do that in this case,
33 and thus avoid unnecessary screen redrawing.
34 If rows and/or cols is not NULL, they receive the new geometry.
36
38 If your program is in a render loop (i.e. rendering as quickly as pos‐
39 sible, or at least at the refresh rate), there's not much point in
40 erecting the machinery to trigger notcurses_refresh based off NCKEY_RE‐
41 SIZE. The latter is generated based upon receipt of the SIGWINCH sig‐
42 nal, which is fundamentally racy with regards to the rest of the pro‐
43 gram. If your program truly relies on timely invocation of notcurs‐
44 es_refresh, it's a broken program. If you don't rely on it in a causal
45 fashion, then just wait for the upcoming render.
46 Highest performance in a rendering loop would actually call for dis‐
48 abling Notcurses's SIGWINCH handling in the call to notcurses_init, so
49 that no time is spent handling a signal you're not going to use.
50 Each time notcurses_refresh is successfully executed, the refreshes
52 stat is incremented by 1.
53
55 Returns 0 on success, and -1 on failure. The causes for failure in‐
56 clude system error, programming error, closing of output, or allocation
57 failure. None of these are particularly good things, and the most rea‐
58 sonable response to a notcurses_refresh failure is either to ignore it,
59 or to weep and exit.
60
62 notcurses_init(3), notcurses_input(3), notcurses_render(3), notcurs‐
63 es_stats(3), termios(3), signal(7)
64
66 nick black <nickblack@linux.com>.
67 v2.2.3 notcurses_refresh(3)