Return to intro.3 CVS log

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

Annotation of 43BSDReno/share/doc/ps1/18.curses/intro.3, 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.3     6.2 (Berkeley) 3/17/89
        !            17: .\"
        !            18: .sh 1 Usage
        !            19: .pp
        !            20: This is a description of how to actually use the screen package.
        !            21: In it, we assume all updating, reading, etc.
        !            22: is applied to
        !            23: .Vn stdscr .
        !            24: All instructions will work on any window,
        !            25: with changing the function name and parameters as mentioned above.
        !            26: .sh 2 "Starting up"
        !            27: .pp
        !            28: In order to use the screen package,
        !            29: the routines must know about terminal characteristics,
        !            30: and the space for
        !            31: .Vn curscr
        !            32: and
        !            33: .Vn stdscr
        !            34: must be allocated.
        !            35: These functions are performed by
        !            36: .Fn initscr .
        !            37: Since it must allocate space for the windows,
        !            38: it can overflow core when attempting to do so.
        !            39: On this rather rare occasion,
        !            40: .Fn initscr
        !            41: returns ERR.
        !            42: .Fn initscr
        !            43: must
        !            44: .bi always
        !            45: be called before any of the routines which affect windows are used.
        !            46: If it is not,
        !            47: the program will core dump as soon as either
        !            48: .Vn curscr
        !            49: or
        !            50: .Vn stdscr
        !            51: are referenced.
        !            52: However, it is usually best to wait to call it
        !            53: until after you are sure you will need it,
        !            54: like after checking for startup errors.
        !            55: Terminal status changing routines
        !            56: like
        !            57: .Fn nl
        !            58: and
        !            59: .Fn cbreak
        !            60: should be called after
        !            61: .Fn initscr .
        !            62: .pp
        !            63: Now that the screen windows have been allocated,
        !            64: you can set them up for the run.
        !            65: If you want to, say, allow the window to scroll,
        !            66: use
        !            67: .Fn scrollok .
        !            68: If you want the cursor to be left after the last change, use
        !            69: .Fn leaveok .
        !            70: If this isn't done,
        !            71: .Fn refresh
        !            72: will move the cursor to the window's current \*y after updating it.
        !            73: New windows of your own can be created, too, by using the functions
        !            74: .Fn newwin
        !            75: and
        !            76: .Fn subwin .
        !            77: .Fn delwin
        !            78: will allow you to get rid of old windows.
        !            79: If you wish to change the official size of the terminal by hand,
        !            80: just set the variables
        !            81: .Vn LINES
        !            82: and
        !            83: .Vn COLS
        !            84: to be what you want,
        !            85: and then call
        !            86: .Fn initscr .
        !            87: This is best done before,
        !            88: but can be done either before or after,
        !            89: the first call to
        !            90: .Fn initscr ,
        !            91: as it will always delete any existing
        !            92: .Vn stdscr
        !            93: and/or
        !            94: .Vn curscr
        !            95: before creating new ones.
        !            96: .pp
        !            97: .sh 2 "The Nitty-Gritty"
        !            98: .sh 3 Output
        !            99: .pp
        !           100: Now that we have set things up,
        !           101: we will want to actually update the terminal.
        !           102: The basic functions
        !           103: used to change what will go on a window are
        !           104: .Fn addch
        !           105: and
        !           106: .Fn move .
        !           107: .Fn addch
        !           108: adds a character at the current \*y,
        !           109: returning ERR if it would cause the window to illegally scroll,
        !           110: .i i.e. ,
        !           111: printing a character in the lower right-hand corner
        !           112: of a terminal which automatically scrolls
        !           113: if scrolling is not allowed.
        !           114: .Fn move
        !           115: changes the current \*y to whatever you want them to be.
        !           116: It returns ERR if you try to move off the window when scrolling is not allowed.
        !           117: As mentioned above, you can combine the two into
        !           118: .Fn mvaddch
        !           119: to do both things in one fell swoop.
        !           120: .pp
        !           121: The other output functions,
        !           122: such as
        !           123: .Fn addstr
        !           124: and
        !           125: .Fn printw ,
        !           126: all call
        !           127: .Fn addch
        !           128: to add characters to the window.
        !           129: .pp
        !           130: After you have put on the window what you want there,
        !           131: when you want the portion of the terminal covered by the window
        !           132: to be made to look like it,
        !           133: you must call
        !           134: .Fn refresh .
        !           135: In order to optimize finding changes,
        !           136: .Fn refresh
        !           137: assumes that any part of the window not changed
        !           138: since the last
        !           139: .Fn refresh
        !           140: of that window has not been changed on the terminal,
        !           141: .i i.e. ,
        !           142: that you have not refreshed a portion of the terminal
        !           143: with an overlapping window.
        !           144: If this is not the case,
        !           145: the routines
        !           146: .Fn touchwin ,
        !           147: .Fn touchline ,
        !           148: and
        !           149: .Fn touchoverlap
        !           150: are provided to make it look like a desired part of window has been changed,
        !           151: thus forcing
        !           152: .Fn refresh
        !           153: check that whole subsection of the terminal for changes.
        !           154: .pp
        !           155: If you call
        !           156: .Fn wrefresh
        !           157: with
        !           158: .Vn curscr ,
        !           159: it will make the screen look like
        !           160: .Vn curscr
        !           161: thinks it looks like.
        !           162: This is useful for implementing a command
        !           163: which would redraw the screen in case it get messed up.
        !           164: .sh 3 Input
        !           165: .pp
        !           166: Input is essentially a mirror image of output.
        !           167: The complementary function to
        !           168: .Fn addch
        !           169: is
        !           170: .Fn getch
        !           171: which,
        !           172: if echo is set,
        !           173: will call
        !           174: .Fn addch
        !           175: to echo the character.
        !           176: Since the screen package needs to know what is on the terminal at all times,
        !           177: if characters are to be echoed,
        !           178: the tty must be in raw or cbreak mode.
        !           179: If it is not,
        !           180: .Fn getch
        !           181: sets it to be cbreak,
        !           182: and then reads in the character.
        !           183: .sh 3 Miscellaneous
        !           184: .pp
        !           185: All sorts of fun functions exists for maintaining and changing information
        !           186: about the windows.
        !           187: For the most part,
        !           188: the descriptions in section 5.4. should suffice.
        !           189: .sh 2 "Finishing up"
        !           190: .pp
        !           191: In order to do certain optimizations,
        !           192: and,
        !           193: on some terminals,
        !           194: to work at all,
        !           195: some things must be done
        !           196: before the screen routines start up.
        !           197: These functions are performed in
        !           198: .Fn getttmode
        !           199: and
        !           200: .Fn setterm ,
        !           201: which are called by
        !           202: .Fn initscr .
        !           203: In order to clean up after the routines,
        !           204: the routine
        !           205: .Fn endwin
        !           206: is provided.
        !           207: It restores tty modes to what they were
        !           208: when
        !           209: .Fn initscr
        !           210: was first called.
        !           211: Thus,
        !           212: anytime after the call to initscr,
        !           213: .Fn endwin
        !           214: should be called before exiting.

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