Fresh Fish 5

home *** CD-ROM | disk | FTP | other *** search

/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / curses-1.4.lha / Curses-1.4 / curses.doc < prev next >

Wrap

Text File | 1994-02-22 | 22.6 KB | 817 lines

AMIGA CURSES PACKAGE ==================== Author : Simon John Raybould (sie@fulcrum.co.uk) Mod Date : 14th August 1992 Version ======= $Id: curses.doc,v 1.4 1993/06/12 20:24:20 sie Exp $ Modification History ==================== $Log: curses.doc,v $ Revision 1.4 1993/06/12 20:24:20 sie Minor updates Revision 1.3 92/06/29 22:33:08 sie Added some more function descriptions. Revision 1.2 92/06/23 22:38:14 sie Documentation for amiga curses library. Description =========== Curses is a screen manipulation package that is used quite extensively in the UNIX environment. I wrote this because I had several UNIX programs that used curses that I wanted to port to the Amiga. Version 2.00 and above now support ANSI sequences to allow curses applications to be executes through the serial port to a terminal or over a modem to a terminal or terminal package such as "Term20" or "jrcomm". To enable this, simply set the environment variable "cursestype" to "ansi" before running the program. If this variable is not set, curses will open a custom screen. The default number of colours for the custom screen is now 2 (black and white). To enable 8 colours, call start_color() before initscr(). has_colors() will return TRUE if start_color() has been called else it will return FALSE. If you require further documentation to that provided here then I would recommend: "Programming with curses" by John Strang ISBN 0-937175-02-1 published by O'Reilly & Associates, Inc. This book is very good and very cheap (10 pound in the UK). Short descriptions of functions provided ======================================== int initscr(void) This must be called before any window can be created or manipulated. It creates "stdscr" and "curscr". curscr is a copy of what curses thinks is currently on the display. Calling wrefresh(curscr) will redraw the entire screen and is useful for noisy modem lines. This is usually called when the user types ^L or sometimes ^R in older programs. Return value ============ On Success, OK is returned. On error, ERR is returned int endwin(void) This should be called before exiting a curses program. It frees all memory used and dismantles all structures. It closes the custom screen and window used if curses is used in non-ANSI mode. Return value ============ On Success, OK is returned. On error, ERR is returned int beep(void) Produces an audible beep from the speaker. This beep is similar in pitch and duration to the beep from a terminal when a BEL (^G) character is received. If curses is running in ANSI mode, a BEL character will be sent to the terminal. Return value ============ On Success, OK is returned. On error, ERR is returned int flash(void) Flashes the display by complementing the background colour. With the default black background, this will flash the screen yellow. If curses is being used in ANSI mode, a BEL character will be sent to the terminal. Return value ============ On Success, OK is returned. On error, ERR is returned int baudrate(void) Returns current baudrate. On the Amiga, it just returns 19200. It is used to decide how much to refresh over slow serial lines such as modems. Return value ============ 19200 is returned. int box(WINDOW *win, char vert, char hor) Draws a box around the INSIDE edge of the window. win - pointer returned from newwin or subwin, or stdscr even. vert - character to use for the vertical. hor - character to use for the horizontal. Either of the characters may be zero. In this case, the defaults of "|" and "-" will be used for vertical and horizontal respectively. NOTE ---- The box drawn is INSIDE the window. Therefore any of the clear routines will effect the box if carried out on its window. The normal thing to do is open two windows, one for the box two columns wider and two lines higher than the window for the text. Then use the inner window for the text. This way the box is only drawn once. Return value ============ On Success, OK is returned. On error, ERR is returned int cbreak(void) int nocbreak(void) cbreak() puts the terminal into CBREAK mode, making characters typed available immediately. nocbreak() sets NOCBREAK mode and characters are not available until carriage return is pressed. The default is NOCBREAK mode, so most programs call cbreak() before doing any reads on the keyboard for interactive use. Return value ============ On Success, OK is returned. On error, ERR is returned int crmode(void) int nocrmode(void) As cbreak() and nocbreak() as shown above. Return value ============ On Success, OK is returned. On error, ERR is returned int clearok(WINDOW *win, int flag) If flag is TRUE then it is OK to clear the window on the next refresh. Return value ============ On Success, OK is returned. On error, ERR is returned int leaveok(WINDOW *win, int flag) If flag is TRUE then curses doesn"t care where it leaves the cursor. If possible, the cursor will not be displayed. The default is FALSE and the cursor is displayed correctly. Return value ============ On Success, OK is returned. On error, ERR is returned WINDOW *subwin(WINDOW *orig, int lines, int cols, int beg_line, int beg_col) Creates a new window within another window. The original window has its pointer passed as "orig". The new window will be at line "beg_line" and column "beg_col" of the window pointed to by "orig". It will be of size "lines" lines of "cols" columns. A sub-window is part of its surrounding window. When the surrounding window is refreshed, the sub-window is refreshed as well. Return value ============ On success, a pointer to a new window is returned. On failure, a NULL pointer is returned. WINDOW *newwin(int lines, int cols, int beg_line, int beg_col) Creates a new window at line "beg_line" and column "beg_col", "lines" high by "cols" wide. The new window has its own data structures and does not affect any data in other windows. It is only refreshed by a call like wrefresh(win) where "win" was returned by this function. Return value ============ On success, a pointer to a new window is returned. On failure, a NULL pointer is returned. int delwin(WINDOW *win) Deletes a window and frees the associated memory. This should be done if the window is no longer used. It is not necessary to free all windows, endwin() will free all windows still allocated before returning. Return value ============ On Success, OK is returned. On error, ERR is returned int mvwin(WINDOW *win, int new_line, int new_col) Moves a window to a new position on the screen. This position is relative to the top left of the screen and NOT to the start of any surrounding window in the case of sub-windows. Return value ============ On Success, OK is returned. On error, ERR is returned int nl(void) int nonl(void) nl() - Causes newline to newline/carriage return mapping on output and return to newline mapping on input. nonl() - disables this. The DEFAULT is that mapping is done (nl). Return value ============ On Success, OK is returned. On error, ERR is returned int echo(void) int noecho(void) echo() causes characters read from the keyboard to be echoed to the display. noecho() prevents the echo, this is useful when reading keys that you don"t want echoed to the screen. The DEFAULT is that echoing is performed (echo). Return value ============ On Success, OK is returned. On error, ERR is returned int nodelay(WINDOW *win, int flag) nodelay() sets nodelay mode if "flag" is TRUE. When in nodelay mode, getch() will return ERR if there is no input pending. The DEFAULT is nodelay not set and getch() will block, waiting for at least one char in CBREAK mode or a line followed by carriage return in non CBREAK mode. Return value ============ On Success, OK is returned. On error, ERR is returned int has_colors(void) int start_color(void) int init_color(int n, int r, int g, int b) has_colors() is to check if colours are available on this terminal. On the Amiga, it will return TRUE if start_color() has been called else it will return FALSE. start_colour() is to tell the terminal that you wish to use colour. In Amiga curses, this MUST be called before initscr() or it will have no effect because initscr() sets up the screen and needs to know how many colours you want. init_color() will alter the Red, Green and Blue content of colour n. r, g and b are in the range 1 to 1000. The colour number "n" is in the range 0 to 15 and it should be noted that colour 0 is the background colour. Initially the foreground is set to colour 1 but can be changed with the attron() or attrset() function to any of the colours 1 to 15, 0 is not allowed as this is the background. If 0 is selected, the foreground colour will be set to 1. Return value ============ On Success, OK is returned. On error, ERR is returned int keypad(WINDOW *win, int flag) If "flag" is TRUE then the ANSI sequences for the function keys and the cursor keys will be converted to the tokens KEY_UP, KEY_HELP, e.t.c. The DEFAULT is that the ANSI sequences will returned. So to cause special keys to be returned as tokens in the standard screen, add the following line: keypad(stdscr, TRUE); Return value ============ On Success, OK is returned. On error, ERR is returned int printw(char *fmt, ...) int wprintw(WINDOW *win, char *fmt, ...) int mvprintw(int line, int col, char *fmt, ...) int mvwprintw(WINDOW *win, int line, int col, char *fmt, ...) Produce formatted output similar to printf(3). printw() - prints at the current position in stdscr. wprintw() - prints at the current position in win. mvprintw() - prints at line "line" column "col" in stdscr. mvwprintw() - prints at line "line" column "col" in "win". Return value ============ On Success, number of formats successfully replaced is returned. On error, -1 is returned. scanw(char *fmt, ...) wscanw(WINDOW *win, char *fmt, ...) mvscanw(int line, int col, char *fmt, ...) mvwscanw(WINDOW *win, int line, int col, char *fmt, ...) Produce formatted input similar to scanf(3). scanw() - scans at the current position in stdscr. wscanw() - scans at the current position in win. mvscanw() - scans at line "line" column "col" in stdscr. mvwscanw() - scans at line "line" column "col" in "win". Return value ============ On Success, number of formats successfully replaced is returned. On error, -1 is returned. int scrollok(WINDOW *win, int flag) When flag is true, curses will automatically scroll the window up one line when output goes off the bottom of "win". E.g. scrollok(stdscr, TRUE); "stdscr" will then be automatically scrolled up one line when output goes off bottom. The DEFAULT is that the window will NOT be scrolled, the bottom line will be used over and over again without scrolling. Return value ============ On Success, OK is returned. On error, ERR is returned int scroll(WINDOW *win) The window "win" is scrolled up one line. Return value ============ On Success, OK is returned. On error, ERR is returned int setscrreg(int top, int bottom) int wsetscrreg(WINDOW *win, int top, int bottom) Sets the scrolling region from line "top" to line "bottom" inclusive. Only the region between these two lines is scrolled when scroll() is called or when output moves off the end of line "bottom", the region is scrolled up one line (if scrollok() has been called). Return value ============ On Success, OK is returned. On error, ERR is returned int touchwin(WINDOW *win) Will force the window to be completely refreshed on the next call to refresh() by dumping all optimization information. This can be useful if the state of the screen is unknown or if a window was obscured by another window which was not a subwindow of the one it covered. Then you may need to touchwin() the window that was covered and refresh it. If you have several windows and wish to redraw the entire display, such as when ^L is pressed in many applications, you could touchwin all of your windows, clear the screen and refresh each one in turn. The recommended way to do this however is to simply wrefresh(curscr). Return value ============ On Success, OK is returned. On error, ERR is returned int addch(char c) int waddch(WINDOW *win, char c) int mvaddch(int int line, int col, char c) int mvwaddch(WINDOW *win, int line, int col, char c) addch(c) - Prints character "c" at current screen position in "stdscr". waddch(win, c) - Prints character "c" at current screen position in "win". mvaddch(line, col, c) - Prints character "c" at line "line" column "col" in "stdscr". mvwaddch(win, line, col, c) - Prints character "c" at line "line" column "col" in win. Return value ============ On Success, OK is returned. On error, ERR is returned int addstr(char *str) int waddstr(WINDOW *win, char *str) int mvaddstr(int line, int col, char *str) int mvwaddstr(WINDOW *win, int line, int col, char *str) addstr(str) - Prints string "str" at the current screen position in "stdscr". waddstr(win, str) - Prints string "str" at current screen position in "win". mvaddstr(line, col, str) - Prints string "str" at line "line" column "col" in "stdscr". mvwaddstr(win, line, col, str) - Prints string "str" at line "line" column "col" in window "win". Return value ============ On Success, OK is returned. On error, ERR is returned int attrset(UBYTE attrs) int wattrset(WINDOW *win, UBYTE attrs) These routines set the attributes for "stdscr" or the specified window (in the case of wattrset()) to the value specified in "attrs". This is usually used to get the attributes to a known state before using attron() and attroff() to add and remove extra attributes respectively. The danger is that all previous attributes are lost and replaced by the new ones. Consequently they are not really necessary. See attron() and attroff(). Return value ============ On Success, OK is returned. On error, ERR is returned int attron(UBYTE attrs) int wattron(WINDOW *win, UBYTE attrs) These routines add the attributes specified in "attrs" to those already set for "stdscr" or the window specified (in the case of wattron()). Any previous attributes that are not directly affected by the changes will be left as they were. This is the preferred way to set and unset attributes as it has no effect on other attributes. Return value ============ On Success, OK is returned. On error, ERR is returned int attroff(UBYTE attrs) int wattroff(WINDOW *win, UBYTE attrs) These routines remove the attributes specified in attrs from those set for stdscr or the window specified in the case of wattroff(). Any previous attributes that are not directly affected by the changes will be left as they were. This is the preferred method of resetting attributes rather than calling attrset. Example: attron(A_REVERSE) addstr("This is in inverse"); attroff(A_REVERSE); refresh(); Return value ============ On Success, OK is returned. On error, ERR is returned int standout(void) int wstandout(WINDOW *win) int standend(void) int wstandend(WINDOW *win) These routines set and reset inverse video mode. Example ======= standout(); addstr("This is inverse video"); standend(); addstr("This is normal video"); refresh(); Return value ============ On Success, OK is returned. On error, ERR is returned int erase(void) int werase(WINDOW *win) These routines will empty the screen buffer and will cause the screen to be cleared on the next call to refresh(). Return value ============ On Success, OK is returned. On error, ERR is returned int clear(void) int wclear(WINDOW *win) These routines will empty the screen buffer and will cause the screen to be cleared on the next call to refresh(). Similar to erase() except that these will call clearok() as well. If possible, a clear sequence will be sent to the screen whereas erase() just fills the buffer with spaces. Return value ============ On Success, OK is returned. On error, ERR is returned int clrtobot(void) int wclrtobot(WINDOW *win) On the next call to refresh(), the window will be cleared from the current position to bottom righthand corner. Return value ============ On Success, OK is returned. On error, ERR is returned int clrtoeol(void) int wclrtoeol(win) On the next call to refresh(), the window will be cleared from the current position to the end of the line. Return value ============ On Success, OK is returned. On error, ERR is returned int delch(void) int wdelch(WINDOW *win) int mvdelch(int line, int col) int mvwdelch(WINDOW *win, int line, int col) These routines delete the character at the current position, the rest of the line to the right of this character is slid along to the left to fill the gap. This can be very useful in editors and the like. Return value ============ On Success, OK is returned. On error, ERR is returned int getch(void) int wgetch(WINDOW *win) int mvgetch(int line, int col) int mvwgetch(WINDOW *win, int line, int col) These routines return the next character from the keyboard. If cbreak() has been called then they return as soon as there is a character to read else they wait for a <CR> before returning. If nodelay() has been called then they will return a character if there is one or ERR if not. Return value ============ On Success, the character read is returned. On error, ERR is returned int getstr(void) int wgetstr(WINDOW *win) int mvgetstr(int line, int col) int mvwgetstr(WINDOW *win, int line, int col) These routines should be used to read a string in from the keyboard. Delete is processed for you. Return value ============ On Success, OK is returned. On error, ERR is returned int inch(void) int winch(WINDOW *win) int mvinch(int line, int col) int mvwinch(WINDOW *win, int line, int col) These routines return the character at the current position in the window or stdscr if the window is not required. The routines that take a line and column move the cursor to that position in the window and then return the char at that position. Return value ============ On Success, OK is returned. On error, ERR is returned int insch(void) int winsch(WINDOW *win) int mvinsch(int line, int col) int mvwinsch(WINDOW *win, int line, int col) These routines insert a character at the current window position, or at the specified position in the "mv" cases. The remainder of the line is shifted along to the right to make room. The character at the far right is lost. Return value ============ On Success, OK is returned. On error, ERR is returned int insertln(void) int winsterln(WINDOW *win) These routines insert one line at the current window position. All of the lines below are shifted down and the bottom line is lost. Return value ============ On Success, OK is returned. On error, ERR is returned int deleteln(void) int wdeleteln(WINDOW *win) These routines delete one line at the current window position. All of the lines below are shifted up into the space and the bottom line is left blank. Return value ============ On Success, OK is returned. On error, ERR is returned int move(int line, int col) int wmove(WINDOW *win, int line, int col) These routines set the current coordinates to "line" and "col". The next text added to this window will then go at this position. Return value ============ On Success, OK is returned. On error, ERR is returned int refresh(void) int wrefresh(WINDOW *win) refresh() will cause all outstanding characters for stdscr to be sent. wrefresh() will do the same a refresh but on the window specified. Return value ============ On Success, OK is returned. On error, ERR is returned int wnoutrefresh(WINDOW *win) int doupdate(void) Will cause "win" to be refreshed when doupdate() is next called. You can then wnoutrefresh() several windows and make one call to doupdate() to do all the updates at once. Return value ============ On Success, OK is returned. On error, ERR is returned int fixterm(void) This function does nothing on the Amiga, it is provided to allow programs that use it to link without trouble. Return value ============ OK is returned. int flushinp(void) This function empties the keyboard buffer. It will trash all characters that have been buffered up. Return value ============ OK is returned. int idlok(WINDOW *WinPtr, int flag) This fuction enables hardware insert & delete line. This does not currently have any effect. Return value ============ OK is returned. int saveterm(void) int resetterm(void) saveterm() saves the current terminal settings and resetterm() resets the terminal to the state it was in when the last save was done. On the Amiga, they have no effect. Return value ============ OK is returned. int savetty(void) int resetty(void) savetty() saves the current terminal settings and resettty() resets the terminal to the state it was in when the last save was done. On the Amiga, they have no effect. Return value ============ OK is returned. int mvcur(int oldline, int oldcol, int newline, int newcol) This will move the cursor to the position specified by "newline" and "newcol". The move is immediate and so refresh() does not need to be called, in fact a call to refresh() will cause the cursor to be moved after the last char printed during that refresh. oldline and oldcol are currently ignored. Return value ============ On Success, OK is returned. On error, ERR is returned