A curses program manipulates windows that appear on a terminal's display. A window can be as large as the entire display or as small as a single character in length and height.
Note: Pads are the exception. A pad is a window that is not restricted by the size of the screen.
The figure shows the different types of windows that exist in the curses environment:
Within a curses program, windows are variables declared as type WINDOW. The WINDOW data type is defined in the /usr/include/curses.h file as a C data structure. You create a window by allocating a portion of a machine's memory for a window structure. This structure describes the characteristics of the window. When a program changes the window data internally in memory, it must use the wrefresh subroutine (or equivalent subroutine) to update the external, physical screen to reflect the internal change in the appropriate window structure.
Curses provides a virtual default window called stdscr. The stdscr represents, in memory, the entire terminal display. The stdscr window structure is created automatically when the curses library is initialized and it describes the display. When the library is initialized, the length and width variables are set to the length and width of the physical display.
Programs that use the stdscr first manipulate the stdscr and then call the refresh subroutine to refresh the external display so that it matches the stdscr window.
In addition to the stdscr, you can define your own windows. These windows are known as user-defined windows to distinguish them from the stdscr. Like the stdscr, user-defined windows exist in machine memory as structures. Except for the amount of memory available to a program, there is no limit to the number of windows you can create. A curses program can manipulate the default window, user-defined windows, or both.
Curses supports another virtual window called curscr (current screen). The curscr window is an internal representation of what currently appears on the terminal's external display.
When a program requires the external representation to match the internal representation, it must call a subroutine, such as the wrefresh subroutine, to update the physical display (or the refresh subroutine if the program is working with the stdscr).
| refresh, or wrefresh | Updates the terminal and curscr to reflect changes made to a window. |
The curscr is reserved for internal use by curses. You should not manipulate the curscr.
Curses also allows you to construct subwindows. Subwindows are rectangular portions within other windows. A subwindow is also of type WINDOW. The window that contains a subwindow is known as the subwindow's parent and the subwindow is known as the containing window's child. The figure demonstrates the parent child relationship.
Changes to either the parent window or the child window within the area overlapped by the subwindow are made to both windows. After modifying a subwindow, you should call the touchline or touchwin subroutine on the parent window before refreshing it.
| 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. |
A refresh called on the parent refreshes the children as well.
A subwindow can also be a parent window. The process of layering windows inside of windows is called nesting.
Before you can delete a parent window, you must first delete all of its children using the delwin subroutine.
| delwin | Removes a window data structure. |
Curses returns an error if you try to delete a window before removing all of its children.
A pad is a type of window that is not restricted by the terminal's display size or associated with a particular part of the display. Because a pad is usually larger than the physical display, only a portion of a pad is visible to the user at a given time.
Use pads if you have a large amount of related data that you want to keep all together in one window but you do not need to display all of the data at once.
Windows within pads are known as subpads. Subpads are positioned within a pad at coordinates relative to the parent pad. This placement differs from subwindows which are positioned using screen coordinates.
| prefresh or pnoutrefresh | Updates the terminal and curscr to reflect changes made to a pad. |
Unlike other windows, scrolling or echoing of input does not automatically refresh a pad. Like subwindows, when changing the image of a subpad, you must call either the touchline or touchwin subroutine on the parent pad before refreshing the parent.
You can use all the curses subroutines with pads except for the newwin, subwin, wrefresh, and wnoutrefresh subroutines. These subroutines are replaced with the newpad, subpad, prefresh, and pnoutrefresh subroutines.
Curses Overview for Programming
List of Additional Curses Subroutines
