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:
You can create your own window using the newwin subroutine.
| newwin | Creates a new window data structure. |
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 number of nested subwindows is limited to the amount of memory available up to the value of SHRT_MAX as defined in the /usr/include/limits.h file.
You can change windows without regard to the order in which they were created. Updates to the terminal's display occur through calls to the wrefresh subroutine.
| subwin | Creates a subwindow of 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.
| newpad | Creates a new pad data structure. |
| subpad | Creates and returns a pointer to a subpad 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, 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.
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:
| refresh, or wrefresh | Updates the terminal and curscr to reflect changes made to a window. |
| wnoutrefresh or doupdate | Updates the designated windows and outputs them all at once to the terminal. These subroutines are useful for faster response when there are multiple updates. |
The refresh and wrefresh 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.
| prefresh or pnoutrefresh | Updates the terminal and curscr to reflect changes made to a user-defined pad. |
The prefresh subroutine updates both the current screen and the physical display, while 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.
| touchline | Forces a range of lines to be refreshed at the next call to the wrefresh subroutine. |
| touchwin | Forces every character in a window's character array to be refreshed at the next call of the wrefresh subroutine. The touchwin subroutine does not save optimization information. This subroutine is useful with overlapping windows. |
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 becomeS 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.
| box | Draws a box in or around a window. |
| copywin | Provides more precise control over the overlay and overwrite subroutine. |
| garbagedlines | Indicates to curses that a screen line is garbaged and should be thrown away before having anything written over the top of it. |
| mvwin | Moves a window or subwindow to a new location. |
| overlay or overwrite | Copies one window on top of another. |
| ripoffline | Removes a line from the default screen. |
The mvwin subroutine moves a window or subwindow. The box subroutine draws a box around the edge of a window or subwindow.
To use the overlay and overwrite 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.
| filter | Sets the size of the terminal screen to 1 line. |
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