1notcurses_refresh(3)                                      notcurses_refresh(3)
2
3
4

NAME

6       notcurses_refresh - redraw an externally-damaged display
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11       int  notcurses_refresh(const  struct notcurses* nc, int* restrict rows,
12       int* restrict cols);
13

DESCRIPTION

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
28       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
35       If rows and/or cols is not NULL, they receive the new geometry.
36

NOTES

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
47       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
51       Each  time  notcurses_refresh  is  successfully executed, the refreshes
52       stat is incremented by 1.
53

RETURN VALUES

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

SEE ALSO

62       notcurses_init(3),  notcurses_input(3),  notcurses_render(3),  notcurs‐
63       es_stats(3), termios(3), signal(7)
64

AUTHORS

66       nick black <nickblack@linux.com>.
67
68
69
70                                    v2.3.1                notcurses_refresh(3)
Impressum