1.\" $NetBSD: curses_refresh.3,v 1.13 2017/01/05 09:46:32 wiz Exp $ 2.\" 3.\" Copyright (c) 2002 4.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) 5.\" 6.\" This code is donated to the NetBSD Foundation by the Author. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of the Author may not be used to endorse or promote 17.\" products derived from this software without specific prior written 18.\" permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" 33.Dd January 2, 2017 34.Dt CURSES_REFRESH 3 35.Os 36.Sh NAME 37.Nm curses_refresh , 38.Nm refresh , 39.Nm wrefresh , 40.Nm wnoutrefresh , 41.Nm doupdate , 42.Nm immedok , 43.Nm flushok , 44.Nm leaveok , 45.Nm is_leaveok 46.Nd curses terminal update routines 47.Sh LIBRARY 48.Lb libcurses 49.Sh SYNOPSIS 50.In curses.h 51.Ft int 52.Fn refresh "void" 53.Ft int 54.Fn wrefresh "WINDOW *win" 55.Ft int 56.Fn wnoutrefresh "WINDOW *win" 57.Ft int 58.Fn doupdate "void" 59.Ft int 60.Fn immedok "WINDOW *win" "boolf flag" 61.Ft int 62.Fn flushok "WINDOW *win" "boolf flag" 63.Ft int 64.Fn leaveok "WINDOW *win" "boolf flag" 65.Ft bool 66.Fn is_leaveok "const WINDOW *win" 67.Sh DESCRIPTION 68These functions update the terminal with the contents of 69.Dv stdscr 70or of the specified window(s). 71.Pp 72The 73.Fn refresh 74function causes curses to propagate changes made to 75.Dv stdscr 76to the terminal display. 77Any changes made to subwindows of 78.Dv stdscr 79are also propagated. 80.Pp 81The 82.Fn wrefresh 83function is the same as the 84.Fn refresh 85function, excepting that changes are propagated to the terminal from the 86window specified by 87.Fa win . 88.Pp 89The 90.Fn wnoutrefresh 91function performs the internal processing required by curses to determine 92what changes need to be made to synchronise the internal screen buffer 93and the terminal but does not modify the terminal display. 94.Pp 95The 96.Fn doupdate 97function updates the terminal display to match the internal curses 98representation of the display. 99.Pp 100The 101.Fn wnoutrefresh 102and 103.Fn doupdate 104functions can be used together to speed up terminal redraws by 105deferring the actual terminal updates until after a batch of updates 106to multiple windows has been done. 107.Pp 108The 109.Fn refresh 110function is equivalent to 111.Fn wnoutrefresh stdscr 112followed by 113.Fn doupdate . 114.Pp 115The 116.Fn immedok 117function determines whether the screen is refreshed whenever the window is 118changed. 119The initial state is 120.Dv FALSE . 121.Pp 122The 123.Fn flushok 124function is used to determine whether or not the screen's output file 125descriptor will be flushed on refresh. 126Setting 127.Fa flag 128to 129.Dv TRUE 130will cause the output to be flushed. 131.Pp 132The 133.Fn leaveok 134function determines whether refresh operations may leave the screen cursor 135in an arbitrary position on the screen. 136Setting 137.Fa flag 138to 139.Dv FALSE 140ensures that the screen cursor is positioned at the current cursor 141position after a refresh operation has taken place. 142The 143.Fn is_leaveok 144function returns the setting. 145.Sh RETURN VALUES 146Functions returning pointers will return 147.Dv NULL 148if an error is detected. 149The functions that return an int will return one of the following 150values: 151.Pp 152.Bl -tag -width ERR -compact 153.It Er OK 154The function completed successfully. 155.It Er ERR 156An error occurred in the function. 157.El 158.Sh SEE ALSO 159.Xr curses_pad 3 , 160.Xr curses_touch 3 , 161.Xr getch 3 162.Sh NOTES 163Calling 164.Fn wrefresh 165on a new, unchanged window has no effect. 166.Sh STANDARDS 167The 168.Nx 169Curses library complies with the X/Open Curses specification, part of the 170Single Unix Specification. 171.Sh HISTORY 172The Curses package appeared in 173.Bx 4.0 . 174The 175.Fn is_leaveok 176function is a 177.Em ncurses 178extension to the Curses library and was added in 179.Nx 8.0 . 180