Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
notcurses_refresh(3)					  notcurses_refresh(3)

NAME
       notcurses_refresh - redraw an externally-damaged	display

SYNOPSIS
       #include	<notcurses/notcurses.h>

       int  notcurses_refresh(const  struct  notcurses*	nc, unsigned* restrict
       rows, unsigned* restrict	cols);

DESCRIPTION
       notcurses_refresh clears	the screen, homes the cursor, checks the  cur-
       rent  terminal geometry,	and repaints the most recently rendered	frame.
       It can be called	concurrently with all other Notcurses  functions  save
       notcurses_render.  notcurses_refresh ought be called when the screen is
       externally damaged (as occurs when another program writes to the	termi-
       nal, or if your program writes to the terminal using standard I/O).  It
       is  necessary  to  use  notcurses_refresh in such a case	(as opposed to
       simply calling notcurses_render), since notcurses_render	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
       notcurses_refresh,  and	the  user is responsible for requesting	a hard
       redraw.

       A secondary use of this function	is when	the program is blocking	on in-
       put (and	perhaps	not ready to render),  and  receives  an  NCKEY_RESIZE
       event  (see notcurses_input).  In this case, notcurses_refresh will ac-
       quire the new screen parameters,	and repaint what it  can.   If	you're
       prepared	to call	notcurses_render, it's better to do that in this case,
       and thus	avoid unnecessary screen redrawing.

       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 pos-
       sible,  or  at  least  at  the refresh rate), there's not much point in
       erecting	the machinery to trigger notcurses_refresh based off NCKEY_RE-
       SIZE.  The latter is generated based upon receipt of the	SIGWINCH  sig-
       nal,  which  is fundamentally racy with regards to the rest of the pro-
       gram.  If your program truly relies on timely  invocation  of  notcurs-
       es_refresh, 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 dis-
       abling Notcurses's SIGWINCH handling in the call	to notcurses_init,  so
       that no time is spent handling a	signal you're not going	to use.

       Each  time  notcurses_refresh  is  successfully executed, the refreshes
       stat is incremented by 1.

RETURN VALUES
       Returns 0 on success, and -1 on failure.	 The causes  for  failure  in-
       clude system error, programming error, closing of output, or allocation
       failure.	 None of these are particularly	good things, and the most rea-
       sonable response	to a notcurses_refresh failure is either to ignore it,
       or to weep and exit.

SEE ALSO
       notcurses_init(3),  notcurses_input(3),	notcurses_render(3),  notcurs-
       es_stats(3), termios(3),	signal(7)

AUTHORS
       nick black <nickblack@linux.com>.

				    v3.0.8		  notcurses_refresh(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=notcurses_refresh&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help