When curses is initialized, the stdscr is provided automatically. You can manipulate the stdscr using the curses subroutine library or you can create your own, user-defined windows. This section discusses the following topics as they relate to manipulating window data:
A stdscr is provided by the Curses library when it is initialized. The size of the stdscr is determined by the dimensions of the terminal's display. You can also create your own window using the newwin subroutine.
Each time you call the newwin subroutine, curses allocates a new window structure in memory. This structure contains all the information associated with the new window. Curses does not put a limit on the number of windows you can create. The memory available to your program does restrict the number of windows you can create.
You can change windows without regard to the order in which they were created. For example, you can change a subwindow before changing its parent. Updates to the terminal's display occur through calls to the wrefresh subroutine.
The subwin subroutine creates a subwindow within an existing window. You must supply coordinates for the subwindow relative to the terminal's display. The subwindow must fit within the bounds of the parent window; otherwise, a null value is returned.
The newpad subroutine creates a pad data structure. A pad is not restricted by the size of a terminal's display. You can use the subpad subroutine to create another window within a pad. The new subpad is positioned relative to its parent.
To remove a window, pad, or subwindow, use the delwin subroutine. Before you can delete a window or pad, you must have already deleted its children; otherwise, the delwin subroutine returns an error.
When curses subroutines change the appearance of a window, they are actually manipulating a window structure belonging to either the stdscr or a user-defined window. Changes are not sent immediately to the terminal's display. Instead, the internal representation of the window is updated while the display remains unchanged until the next call to the wrefresh subroutine.
The wrefresh subroutine uses the information in the window structure to update the display. During a refresh, the internal current screen structure is updated to match what is actually on the terminal's display.
Any time you write output to a window or pad structure, you must refresh the terminal's display to match the internal representation. A refresh does the following:
The wrefresh subroutine updates a user-defined window. You use the refresh subroutine to update the stdscr. Both of these subroutines first call the wnoutrefresh subroutine to copy the window being refreshed to the current screen. They then call the doupdate subroutine to update the display.
If you need to refresh multiple windows at the same time, use one of the two available methods. You can use a series of calls to the wrefresh subroutine that result in alternating calls to the wnoutrefresh and doupdate subroutines. You can also call the wnoutrefresh subroutine once for each window and then call the doupdate subroutine once. With the second method, only one burst of output is sent to the display.
The prefresh and pnoutrefresh subroutines are similar to the wrefresh and wnoutrefresh subroutines. The prefresh subroutine updates both the current screen and the physical display to reflect changes made to a user-defined pad. The pnoutrefresh subroutine updates curscr to reflect changes made to a user-defined pad. Because pads instead of windows are involved, these subroutines require additional parameters to indicate which part of the pad and screen are involved.
During a refresh, only those areas that have changed are redrawn on the display. It is possible to refresh areas of the display that have not changed using the touchwin and touchline subroutines.
The touchwin subroutine forces every character in the specified window to be refreshed during the next call to the refresh or wrefresh subroutine. The touchline subroutine forces all the characters in a given range of lines to be refreshed at the next call to the refresh or wrefresh subroutine.
Combining the touchwin and wrefresh subroutines is helpful when dealing with subwindows or overlapping windows. To bring a window forward from behind another window, call the touchwin subroutine followed by the wrefresh subroutine.
If text is sent to the terminal's display with a noncurses subroutine, such as the echo or printf subroutine, the external window can become garbled. In this case, the display changes, but the current screen is not updated to reflect these changes. Problems can arise when a refresh is called on the garbled screen because, after a screen is garbled, there is no difference between the window being refreshed and the current screen structure. As a result, spaces on the display caused by garbled text are not changed.
A similar problem can also occur when a window is moved. The characters sent to the display with the noncurses subroutines do not move with the window internally. If the screen does become garbled, call the wrefresh subroutine on the curscr to update the display to reflect the current physical display.
After a window or subwindow is created, programs often must manipulate them in some way. The mvwin subroutine moves a window or subwindow. The box subroutine draws a box around the edge of a window or subwindow.
The overlay and overwrite subroutines copy text from one window or subwindow on top of another. To use these subroutines, the two windows must overlap. Also, be aware that the overwrite subroutine is destructive whereas the overlay subroutine is not. When text is copied from one window to another using the overwrite subroutine, blank portions from the copied window overwrite any portions of the window copied to. The overlay subroutine is nondestructive because it does not copy blank portions from the copied window.
Similar to the overlay and overwrite subroutines, the copywin subroutine allows you to copy a portion of one window to another. Unlike overlay and overwrite subroutines, the windows do not have to overlap for you to use the copywin subroutine.
You can use the ripoffline subroutine to remove a line from the stdscr. If you pass this subroutine a positive line argument, the specified number of lines is removed from the top of the stdscr. Otherwise, if you pass the subroutine a negative line argument, the lines are removed from the bottom of the stdscr.
Finally, you can use the garbagedlines subroutine to discard a specified range of lines before writing anything new.
The filter subroutine is provided for curses applications that are filters. This subroutine causes curses to operate as if the stdscr was only a single line on the screen. When running with the filter subroutine, curses does not use any terminal capabilities that require knowledge of the line that curses is on.
Curses Overview for Programming, Windows in the Curses Environment.