The procedures in this directory are an implementation of the Unix curses library, with a few deletions and extensions. The procedures have been modified to work in an SPP environment instead of a C environment. Unlike the C routines, they do not return an error status as a function value. In fact, very few of the procedures call error, instead they try to do the most reasonable thing. The mv macros are not implemented, instead the program should call move() followed by the appropriate procedure. Formatted reads and writes to windows are not supported, all reading and writing is done using strings. Subwindows are also not supported. The user program does not have direct access to the window structure, the function winstat() is provided to read fields from the structure. In order to make customization of windows easier, each window can have an input function and data structure bound to it. The functions bindstruct() and getstruct() are provided for this purpose. The forms directory gives several examples of binding functions and data structures to a window. Two other procedures hidewin() and showwin() are provided to hide a window which is currently displayed on the terminal and to redisplay it. The procedure initscr() should be called before using any of the procedures in the curses directory. It initializes the terminal and creates the first window (referred to as STDSCR), which covers the terminal scrren. The procedure endwin() should be called at the end of the user program. It closes any windows which are still open and resets the terminal. Windows are created by calling newwin() and destroyed by calling delwin(). The terminal cursor is moved by the procedure move(). Text is written into a window by the procedures addch() and addstr(). Text is read from the keyboard and displayed in the window by the procedures getch() and getstr(). Changes to the window are not displayed until refresh() is called. Fuller explanations of these and the other curses procedures is given below. Many procedures in this directory exist in two forms. The first form uses the default window, STDSCR. This window is created when initscr() is called and covers the entire screen. The second form uses any window and has an extra argument to specify which window to use. The names of the two forms are the same, except that the second has the letter "w" as the first character. For example, addch() adds a character to STDSCR, while waddch() adds a character to any window. The macro STDSCR is defined in , so it can be used by your program. Many of the procedures in this library operate relative to the current cursor position in that window. To set the cursor position, the program should call move() or wmove() first. Window coordinates are passed row first, column second. The upper left corner of a window is (1,1). procedure addch (ch) procedure waddch (win, ch) pointer win # i: Window descriptor char ch # i: Character to add This procedure adds a single character at the current cursor position. The character currently at that position is overwritten. A linefeed character clears the rest of the line and moves the cursor to the next row. A tab character inserts the apropriate number of spaces at the current position. A carriage return moves the cursor to the first character on the current line. A backspace moves the cursor one column left unless the cursor is in the first column of the window. procedure addstr (str) procedure waddstr (win, str) int win # i: Window descriptor char str[ARB] # i: String to add to window This procedure adds a string at the current cursor position. If part of the string extends beyond the right edge of the window, it will be truncated. Special characters have the same meaning as those in addch(). The window will scroll if scrolling is enabled. procedure bindstruct (func, structure) procedure wbindstruct (win, func, structure) int win # i: Window descriptor extern func # i: Input function pointer structure # i: Data structure This procedure binds an input function and a data structure to a window. The data structure is used by the input function to maintain the window's state. The input function is called by getch() and getstr() to process keyboard input instead of the default procedure, editfn(). The input function should have the following calling sequence. procedure func (win, str, maxch) int win # i: Window descriptor char str[ARB] # io: String containing line int maxch # i: Maximum line length When writing this procedure, the default procedure, editfn() should be used as a guide. The procedure should update the terminal screen, string, and data structure appropriately. When the procedure gets a character indicating input is complete, the character should be pushed back on the input stream with the procedure k_pushbk(). Then the procedure should return the string to the calling program. The calling program can also call getstruct() to retrieve the contents of the data structure. procedure box (win, vert, hor) int win # i: Window descriptor char vert # i: Character used for vertical side of window char hor # i: Character used for horizontal side of window This procedure draws a box around a window. The box is inside the original area of the window, which is then reduced so that subsequent writes to the window will not overwrite the box. procedure clear () procedure wclear (win) int win # i: Window descriptor This procedure clears a window. It is equivalent to calling clearok() with flag set to true, followed by calling erase(). procedure clearok (win, flag) int win # i: Window descriptor bool flag # i: Flag value This procedure sets the clear flag for a window. If the clear flag is true, the entire window will be redrawn when refresh is called. procedure clrtobot () procedure wclrtobot (win) int win # i: Window descriptor This procedure clears a window from the current cursor position to the end of the window. procedure clrtoeol () procedure wclrtoeol (win) int win # i: Window descriptor This procedure clears a window from the current cursor position to the end of the line. procedure delch () procedure wdelch (win) pointer win # i: Window descriptor This procedure deletes the character at the current cursor poisition in the window. Subsequent characters on the line are moved to the left by one. procedure deleteln () procedure wdeleteln (win) pointer win # i: Window descriptor This procedure deletes the current line in the window. Subsequent lines in the window slide up by one and the last line is left blank. procedure delwin (win) This procedure deletes a window created by newwin(). The terminal area that was under the window before it was created is redisplayed. The data structure associated with the window is freed, including the data structure bound by bindstruct(). STDSCR cannot be deleted by this procedure, it is deleted by endwin(). procedure echo () procedure noecho () These procedures turn character echoing on and off. Character echoing is on when the terminal is initialized. If character ecoing is off, procedures addch() and addstr() will return immediately after being called. procedure endwin () This procedure should be called at the end of a program which uses the curses library. It deletes all windows that are still open (including STDSCR) and resets the terminal. procedure erase () procedure werase (win) int win # i: Window descriptor This procedure erases a window, filling it with blanks. int procedure getch () int procedure wgetch (win) This procedure reads a single character from the keyboard and adds it to the window at the current cursor position. If an input function has been bound to the window by bindstruct(), the input procedure is called to process the character. The procedure returns after calling the input function once, regardless of the value of done. The returned character is the first character in the string output by the input function. procedure getstr (str, maxch) procedure wgetstr (win, str, maxch) pointer win # i: Window descriptor char str[ARB] # o: String that was read from the keyboard int maxch # i: Maximum string length This procedure reads a string from the keyboard and displays it in the window at the current cursor position. Editing keys are recognized; however, editing is limited to a single line and keys which change the current line cause the procedure to exit. The default behaviour of this procedure can be modified by binding an input function to the window with bindstruct(). procedure getstruct (structure) procedure wgetstruct (win, structure) int win # i: Window descriptor pointer structure # o: Data structure This procedure returns a pointer to the data structure that was bound to the window by bindstruct(). procedure getyx (win, row, col) int win # i: Window descriptor int row # o: Cursor row int col # o: Cursor column This procedure returns the location of the cursor in a window. The top left corner of a window is (1,1). procedure hidewin (win) int win # i: Window descriptor This procedure hides a window that is currently displayed on the screen. The terminal area under the window is displayed after the window is hidden. The window can be redisplayed by calling showwin(). char procedure inch () char procedure winch (win) pointer win # i: Window descriptor This procedure returns the character at the current cursor location in the window. procedure initscr () This procedure initializes the terminal and creates the default window, STDSCR. It should be called before any other procedure in the curses library is called. procedure insch (ch) procedure winsch (win, ch) pointer win # i: Window descriptor char ch # i: Character to insert This procedure inserts a character at the current cursor position. procedure insertln () procedure winsertln (win) pointer win # i: Window descriptor This procedure inserts a blank line on the current row. The current line and subsequent lines move down by one and the last line in the window is deleted. procedure leaveok (win, flag) int win # i: Window descriptor bool flag # i: Flag value This procedure sets the leave flag for a window. If the leave flag is true, procedures that modify the screen will not move the terminal cursor to the window's current cursor position when the window is modified. If it is false, the terminal cursor position will be moved when the window is updated. When a window is created, the leave flag is set to false. procedure move (row, col) procedure wmove (win, row, col) int win # i: Window descriptor int row # i: Cursor row int col # i: Cursor column This procedure moves the cursor position in a window. Coordinates are relative to those of the window, and the top left corner of a window has the coordinates (1,1) procedure mvwin (win, row, col) int win # i: Window descriptor int row # i: New top row of window int col # i: New left column of window This position moves the position of a window on the screen. The position of a window is the position of the top left corner on the terminal screen. If the new corrdinates would place part of the window off the screen, the coordinates are modified so that the window stays on the screen. int procedure newwin (nrows, ncols, row, col) int nrows # i: Window height int ncols # i: Window width int row # i: Top row of window int col # i: Leftmost column of window This procedure creates a new window. The returned value is the window descriptor, which is used as an argument to the other window functions. The window position is relative to the top left corner of the terminal, which has the coordinates (1,1). If part of the window is off the terminal screen, it will be placed and sized so that the entire window fits on the screen. procedure refresh () procedure wrefresh (win) int win # i: Window descriptor This procedure causes all changes to a window that have been made by other calls in this library to be displayed on the terminal screen. If the clear flag has been set to yes by clearok(), the window will be cleared and redrawn. procedure savewin () procedure nosavewin () These procedures set and unset the save flag. If the save flag is set, whenever a window is created, the area on the terminal screen under is saved in a buffer so it can be restored when the window is hidden or deleted. If a window will exist throughout the life of a program, the save flag can be unset by calling nosavewin() before creating the window so that the memory used to hold the buffer will not be wasted. The save flag is initially set to yes so that all windows have associated screen buffers by default. procedure scrollok (win, flag) int win # i: Window descriptor bool flag # i: Flag value If the scroll flag is set to true, a window will scroll when an attempt is made to write beyond the last line of a window. If the scroll flag is false, the last line of the window will be overwritten. When a new window is created, the scroll flag is set to false. procedure showwin (win) int win # i: Window descriptor This procedure shows a window that was previously hidden by a call to hidewin(). If the window is not hidden, this procedure has no effect. procedure standout () procedure standend () procedure wstandout (win) procedure wstandend (win) int win # i: Window descriptor These procedures modify the character attribute of a window. Calling standout() causes all characters written to the window after the call to be written in standout mode. Calling standend() causes all characacters to be written in normal mode. When a window is created, the character attribute of the window is normal. procedure wdimen (win, nrows, ncols) int win # i: Window descriptor int nrows # o: Window height int ncols # o: Window width This procedure returns the height and width of a window. int procedure winstat (win, what) int win # i: Window descriptor int what # i: Field to retrieve This procedure returns a field from the window descriptor. The field to retrieve is given by a symbolic constant. These constants are listed in the include file .