Copyright (c) 1980, 1993
The Regents of the University of California. All rights reserved.
%sccs.include.redist.roff%
@(#)intro.1 8.1 (Berkeley) 06/04/93
.bp .sh 1 Overview .pp In making available the generalized terminal descriptions in \*(tc, much information was made available to the programmer, but little work was taken out of one's hands. The purpose of this package is to allow the C programmer to do the most common type of terminal dependent functions, those of movement optimization and optimal screen updating, without doing any of the dirty work, and with nearly as much ease as is necessary to simply print or read things. .sh 2 "Terminology" .pp In this document, the following terminology is used: .b "\\$1" : .. p window An internal representation containing an image of what a section of the terminal screen may look like at some point in time. This subsection can either encompass the entire terminal screen, or any smaller portion down to a single character within that screen. p terminal Sometimes called .b terminal .b screen . The package's idea of what the terminal's screen currently looks like, .i i.e. , what the user sees now. This is a special .i screen : p screen This is a subset of windows which are as large as the terminal screen, .i i.e. , they start at the upper left hand corner and encompass the lower right hand corner. One of these, .Vn stdscr , is automatically provided for the programmer. .sh 2 "Compiling Applications" .pp In order to use the library, it is necessary to have certain types and variables defined. Therefore, the programmer must have a line: .(l .b "#include <curses.h>" .)l at the top of the program source. Compilations should have the following form: .(l .)l .sh 2 "Screen Updating" .pp In order to update the screen optimally, it is necessary for the routines to know what the screen currently looks like and what the programmer wants it to look like next. For this purpose, a data type (structure) named .Vn WINDOW is defined which describes a window image to the routines, including its starting position on the screen (the \*y of the upper left hand corner) and its size. One of these (called .Vn curscr for .i "current screen" ) is a screen image of what the terminal currently looks like. Another screen (called .Vn stdscr , for .i "standard screen" ) is provided by default to make changes on. .pp A window is a purely internal representation. It is used to build and store a potential image of a portion of the terminal. It doesn't bear any necessary relation to what is really on the terminal screen. It is more like an array of characters on which to make changes. .pp When one has a window which describes what some part the terminal should look like, the routine .Fn refresh (or .Fn wrefresh if the window is not .Vn stdscr ) is called. .Fn Refresh makes the terminal, in the area covered by the window, look like that window. Note, therefore, that changing something on a window .i does .bi not .i "change the terminal" . Actual updates to the terminal screen are made only by calling .Fn refresh or .Fn wrefresh . This allows the programmer to maintain several different ideas of what a portion of the terminal screen should look like. Also, changes can be made to windows in any order, without regard to motion efficiency. Then, at will, the programmer can effectively say .q "make it look like this" , and the package will execute the changes in an optimal way. .sh 2 "Naming Conventions" .pp As hinted above, the routines can use several windows, but two are always available: .Vn curscr , which is the image of what the terminal looks like at present, and .Vn stdscr , which is the image of what the programmer wants the terminal to look like next. The user should not access .Vn curscr directly. Changes should be made to the appropriate screen, and then the routine .Fn refresh (or .Fn wrefresh ) should be called. .pp Many functions are set up to deal with .Vn stdscr as a default screen. For example, to add a character to .Vn stdscr , one calls .Fn addch with the desired character. If a different window is to be used, the routine .Fn waddch (for .b w indow-specific .Fn addch ) is provided\**. .(f \** Actually, .Fn addch is really a .q #define macro with arguments, as are most of the "functions" which act upon .Vn stdscr . .)f This convention of prepending function names with a q w when they are to be applied to specific windows is consistent. The only routines which do .i not do this are those to which a window must always be specified. .pp In order to move the current \*y from one point to another, the routines .Fn move and .Fn wmove are provided. However, it is often desirable to first move and then perform some I/O operation. In order to avoid clumsiness, most I/O routines can be preceded by the prefix q mv and the desired \*y can then be added to the arguments to the function. For example, the calls .(l move(y\*,x); addch(ch); .)l can be replaced by .(l mvaddch(y\*,x\*,ch); .)l and .(l wmove(win\*,y\*,x); waddch(win\*,ch); .)l can be replaced by .(l mvwaddch(win\*,y\*,x\*,ch); .)l Note that the window description pointer .Vn win ) ( comes before the added \*y. If a window pointer is needed, it is always the first parameter passed.
The Regents of the University of California. All rights reserved.
%sccs.include.redist.roff%
@(#)intro.1 8.1 (Berkeley) 06/04/93
.bp .sh 1 Overview .pp In making available the generalized terminal descriptions in \*(tc, much information was made available to the programmer, but little work was taken out of one's hands. The purpose of this package is to allow the C programmer to do the most common type of terminal dependent functions, those of movement optimization and optimal screen updating, without doing any of the dirty work, and with nearly as much ease as is necessary to simply print or read things. .sh 2 "Terminology" .pp In this document, the following terminology is used: .b "\\$1" : .. p window An internal representation containing an image of what a section of the terminal screen may look like at some point in time. This subsection can either encompass the entire terminal screen, or any smaller portion down to a single character within that screen. p terminal Sometimes called .b terminal .b screen . The package's idea of what the terminal's screen currently looks like, .i i.e. , what the user sees now. This is a special .i screen : p screen This is a subset of windows which are as large as the terminal screen, .i i.e. , they start at the upper left hand corner and encompass the lower right hand corner. One of these, .Vn stdscr , is automatically provided for the programmer. .sh 2 "Compiling Applications" .pp In order to use the library, it is necessary to have certain types and variables defined. Therefore, the programmer must have a line: .(l .b "#include <curses.h>" .)l at the top of the program source. Compilations should have the following form: .(l .)l .sh 2 "Screen Updating" .pp In order to update the screen optimally, it is necessary for the routines to know what the screen currently looks like and what the programmer wants it to look like next. For this purpose, a data type (structure) named .Vn WINDOW is defined which describes a window image to the routines, including its starting position on the screen (the \*y of the upper left hand corner) and its size. One of these (called .Vn curscr for .i "current screen" ) is a screen image of what the terminal currently looks like. Another screen (called .Vn stdscr , for .i "standard screen" ) is provided by default to make changes on. .pp A window is a purely internal representation. It is used to build and store a potential image of a portion of the terminal. It doesn't bear any necessary relation to what is really on the terminal screen. It is more like an array of characters on which to make changes. .pp When one has a window which describes what some part the terminal should look like, the routine .Fn refresh (or .Fn wrefresh if the window is not .Vn stdscr ) is called. .Fn Refresh makes the terminal, in the area covered by the window, look like that window. Note, therefore, that changing something on a window .i does .bi not .i "change the terminal" . Actual updates to the terminal screen are made only by calling .Fn refresh or .Fn wrefresh . This allows the programmer to maintain several different ideas of what a portion of the terminal screen should look like. Also, changes can be made to windows in any order, without regard to motion efficiency. Then, at will, the programmer can effectively say .q "make it look like this" , and the package will execute the changes in an optimal way. .sh 2 "Naming Conventions" .pp As hinted above, the routines can use several windows, but two are always available: .Vn curscr , which is the image of what the terminal looks like at present, and .Vn stdscr , which is the image of what the programmer wants the terminal to look like next. The user should not access .Vn curscr directly. Changes should be made to the appropriate screen, and then the routine .Fn refresh (or .Fn wrefresh ) should be called. .pp Many functions are set up to deal with .Vn stdscr as a default screen. For example, to add a character to .Vn stdscr , one calls .Fn addch with the desired character. If a different window is to be used, the routine .Fn waddch (for .b w indow-specific .Fn addch ) is provided\**. .(f \** Actually, .Fn addch is really a .q #define macro with arguments, as are most of the "functions" which act upon .Vn stdscr . .)f This convention of prepending function names with a q w when they are to be applied to specific windows is consistent. The only routines which do .i not do this are those to which a window must always be specified. .pp In order to move the current \*y from one point to another, the routines .Fn move and .Fn wmove are provided. However, it is often desirable to first move and then perform some I/O operation. In order to avoid clumsiness, most I/O routines can be preceded by the prefix q mv and the desired \*y can then be added to the arguments to the function. For example, the calls .(l move(y\*,x); addch(ch); .)l can be replaced by .(l mvaddch(y\*,x\*,ch); .)l and .(l wmove(win\*,y\*,x); waddch(win\*,ch); .)l can be replaced by .(l mvwaddch(win\*,y\*,x\*,ch); .)l Note that the window description pointer .Vn win ) ( comes before the added \*y. If a window pointer is needed, it is always the first parameter passed.