A curses program manipulates windows that appear on a terminal's display. A window is a rectangular portion of the 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. For more information, see "Pads" .
The following 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 supplies a default window when the Curses library is initialized. You can create your own windows known as user-defined windows. 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 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.
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.
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.
Curses also 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). When a refresh is called on an internal window, curses copies the changed portions of the window into the curscr and updates the physical display.
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 following 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. The touchline and touchwin subroutines instruct curses to discard its optimization information for the parent window and to consider the window as having changed. 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. 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. Before you can delete a parent window, you must first delete all of its children using the delwin subroutine. 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. You can use pads whenever your program requires a large window. 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 when 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.
You should use the prefresh subroutine to show a portion of a pad on the display. 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 subroutine 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
