Return to intro.1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 18.curses

Annotation of 43BSDReno/share/doc/ps1/18.curses/intro.1, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1980 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted
        !             5: .\" provided that the above copyright notice and this paragraph are
        !             6: .\" duplicated in all such forms and that any documentation,
        !             7: .\" advertising materials, and other materials related to such
        !             8: .\" distribution and use acknowledge that the software was developed
        !             9: .\" by the University of California, Berkeley.  The name of the
        !            10: .\" University may not be used to endorse or promote products derived
        !            11: .\" from this software without specific prior written permission.
        !            12: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
        !            13: .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
        !            14: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            15: .\"
        !            16: .\"    @(#)intro.1     6.2 (Berkeley) 3/17/89
        !            17: .\"
        !            18: .bp
        !            19: .sh 1 Overview
        !            20: .pp
        !            21: In making available the generalized terminal descriptions in \*(tc,
        !            22: much information was made available to the programmer,
        !            23: but little work was taken out of one's hands.
        !            24: The purpose of this package is to allow the C programmer
        !            25: to do the most common type of terminal dependent functions,
        !            26: those of movement optimization and optimal screen updating,
        !            27: without doing any of the dirty work,
        !            28: and (hopefully) with nearly as much ease as is necessary to simply print
        !            29: or read things.
        !            30: .pp
        !            31: The package is split into three parts:
        !            32: (1) Screen updating;
        !            33: (2) Screen updating with user input;
        !            34: and
        !            35: (3) Cursor motion optimization.
        !            36: .pp
        !            37: It is possible to use the motion optimization
        !            38: without using either of the other two,
        !            39: and screen updating and input can be done
        !            40: without any programmer knowledge of the motion optimization,
        !            41: or indeed the \*(et \*(db itself.
        !            42: .sh 2 "Terminology (or, Words You Can Say to Sound Brilliant)"
        !            43: .pp
        !            44: In this document,
        !            45: the following terminology is kept to with reasonable consistency:
        !            46: .de Ip
        !            47: .sp
        !            48: .in 5n
        !            49: .ti 0n
        !            50: .bi "\\$1" :
        !            51: ..
        !            52: .Ip window
        !            53: An internal representation
        !            54: containing an image of what a section of the terminal screen may look like
        !            55: at some point in time.
        !            56: This subsection can either encompass the entire terminal screen,
        !            57: or any smaller portion down to a single character within that screen.
        !            58: .Ip "terminal"
        !            59: Sometimes called
        !            60: .bi terminal
        !            61: .bi screen .
        !            62: The package's idea of what the terminal's screen currently looks like,
        !            63: .i i.e. ,
        !            64: what the user sees now.
        !            65: This is a special
        !            66: .i screen :
        !            67: .Ip screen
        !            68: This is a subset of windows which are as large as the terminal screen,
        !            69: .i i.e. ,
        !            70: they start at the upper left hand corner
        !            71: and encompass the lower right hand corner.
        !            72: One of these,
        !            73: .Vn stdscr ,
        !            74: is automatically provided for the programmer.
        !            75: .rm Ip
        !            76: .sh 2 "Compiling Things"
        !            77: .pp
        !            78: In order to use the library,
        !            79: it is necessary to have certain types and variables defined.
        !            80: Therefore, the programmer must have a line:
        !            81: .(l
        !            82: .b "#include <curses.h>"
        !            83: .)l
        !            84: at the top of the program source.
        !            85: The header file
        !            86: .b <curses.h>
        !            87: needs to include
        !            88: .b <sgtty.h> ,
        !            89: so the one should not do so oneself\**.
        !            90: .(f
        !            91: \**
        !            92: The screen package also uses the Standard I/O library,
        !            93: so
        !            94: .b <curses.h>
        !            95: includes
        !            96: .b <stdio.h> .
        !            97: It is redundant
        !            98: (but harmless)
        !            99: for the programmer to do it, too.
        !           100: .)f
        !           101: Also,
        !           102: compilations should have the following form:
        !           103: .(l
        !           104: .ie t \fBcc\fR [ \fIflags\fR ] file ... \fB\-lcurses \-ltermcap\fR
        !           105: .el \fIcc\fR [ flags ] file ... \fI\-lcurses \-ltermcap\fR
        !           106: .)l
        !           107: .sh 2 "Screen Updating"
        !           108: .pp
        !           109: In order to update the screen optimally,
        !           110: it is necessary for the routines to know what the screen currently looks like
        !           111: and what the programmer wants it to look like next.
        !           112: For this purpose,
        !           113: a data type
        !           114: (structure)
        !           115: named
        !           116: .Vn WINDOW
        !           117: is defined
        !           118: which describes a window image to the routines,
        !           119: including its starting position on the screen
        !           120: (the \*y of the upper left hand corner)
        !           121: and its size.
        !           122: One of these
        !           123: (called
        !           124: .Vn curscr
        !           125: for
        !           126: .i "current screen" )
        !           127: is a screen image of what the terminal currently looks like.
        !           128: Another screen
        !           129: (called
        !           130: .Vn stdscr ,
        !           131: for
        !           132: .i "standard screen" )
        !           133: is provided
        !           134: by default
        !           135: to make changes on.
        !           136: .pp
        !           137: A window is a purely internal representation.
        !           138: It is used to build and store
        !           139: a potential image of a portion of the terminal.
        !           140: It doesn't bear any necessary relation
        !           141: to what is really on the terminal screen.
        !           142: It is more like an array of characters on which to make changes.
        !           143: .pp
        !           144: When one has a window which describes
        !           145: what some part the terminal should look like,
        !           146: the routine
        !           147: .Fn refresh
        !           148: (or
        !           149: .Fn wrefresh
        !           150: if the window is not
        !           151: .Vn stdscr )
        !           152: is called.
        !           153: .Fn refresh
        !           154: makes the terminal,
        !           155: in the area covered by the window,
        !           156: look like that window.
        !           157: Note, therefore, that changing something on a window
        !           158: .i does
        !           159: .bi not
        !           160: .i "change the terminal" .
        !           161: Actual updates to the terminal screen
        !           162: are made only by calling
        !           163: .Fn refresh
        !           164: or
        !           165: .Fn wrefresh .
        !           166: This allows the programmer to maintain several different ideas
        !           167: of what a portion of the terminal screen should look like.
        !           168: Also, changes can be made to windows in any order,
        !           169: without regard to motion efficiency.
        !           170: Then, at will,
        !           171: the programmer can effectively say
        !           172: .q "make it look like this" ,
        !           173: and let the package worry about the best way to do this.
        !           174: .sh 2 "Naming Conventions"
        !           175: .pp
        !           176: As hinted above,
        !           177: the routines can use several windows,
        !           178: but two are automatically given:
        !           179: .Vn curscr ,
        !           180: which knows what the terminal looks like,
        !           181: and
        !           182: .Vn stdscr ,
        !           183: which is what the programmer wants the terminal to look like next.
        !           184: The user should never really access
        !           185: .Vn curscr
        !           186: directly.
        !           187: Changes should be made to
        !           188: the appropriate screen,
        !           189: and then the routine
        !           190: .Fn refresh
        !           191: (or
        !           192: .Fn wrefresh )
        !           193: should be called.
        !           194: .pp
        !           195: Many functions are set up to deal with
        !           196: .Vn stdscr
        !           197: as a default screen.
        !           198: For example, to add a character to
        !           199: .Vn stdscr ,
        !           200: one calls
        !           201: .Fn addch
        !           202: with the desired character.
        !           203: If a different window is to be used,
        !           204: the routine
        !           205: .Fn waddch
        !           206: (for
        !           207: .b w indow-specific
        !           208: .Fn addch )
        !           209: is provided\**.
        !           210: .(f
        !           211: \**
        !           212: Actually,
        !           213: .Fn addch
        !           214: is really a
        !           215: .q #define
        !           216: macro with arguments,
        !           217: as are most of the "functions" which deal with
        !           218: .Vn stdscr
        !           219: as a default.
        !           220: .)f
        !           221: This convention of prepending function names with a
        !           222: .Bq w
        !           223: when they are to be applied to specific windows
        !           224: is consistent.
        !           225: The only routines which do
        !           226: .i not
        !           227: do this are those
        !           228: to which a window must always be specified.
        !           229: .pp
        !           230: In order to move the current \*y from one point to another,
        !           231: the routines
        !           232: .Fn move
        !           233: and
        !           234: .Fn wmove
        !           235: are provided.
        !           236: However,
        !           237: it is often desirable to first move and then perform some I/O operation.
        !           238: In order to avoid clumsyness,
        !           239: most I/O routines can be preceded by the prefix
        !           240: .Bq mv
        !           241: and the desired \*y then can be added to the arguments to the function.
        !           242: For example,
        !           243: the calls
        !           244: .(l
        !           245: move(y\*,x);
        !           246: addch(ch);
        !           247: .)l
        !           248: can be replaced by
        !           249: .(l
        !           250: mvaddch(y\*,x\*,ch);
        !           251: .)l
        !           252: and
        !           253: .(l
        !           254: wmove(win\*,y\*,x);
        !           255: waddch(win\*,ch);
        !           256: .)l
        !           257: can be replaced by
        !           258: .(l
        !           259: mvwaddch(win\*,y\*,x\*,ch);
        !           260: .)l
        !           261: Note that the window description pointer
        !           262: .Vn win ) (
        !           263: comes before the added \*y.
        !           264: If such pointers are need,
        !           265: they are always the first parameters passed.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.