Query: intro
OS: ultrix
Section: 3cur
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
intro(3cur) intro(3cur) Name intro - introduction to the X/Open Curses Package, which optimizes terminal screen handling and updating Syntax #include <cursesX.h> cc [ options ] files -lcursesX [ libraries ] Description The (cursor optimization) package is the X/Open set of library routines used for writing screen-management programs. Cursor optimization minimizes the amount the cursor has to be moved around the screen in order to update it. Screen-management programs are used for tasks such as moving the cursor, printing a menu, dividing a terminal screen into windows or drawing a display on a screen for data entry and retrieval. The package is split into three parts: screen updating, screen updating with user input, and cursor motion optimization. Screen-updating routines are used when parts of the screen need to be changed but the overall image remains the same. The cursor motion part of the pack- age can be used separately for tasks such as defining how the cursor moves in response to tabs and newline characters The routines do not write directly to the terminal screen (the physical screen): instead, they write to a window, a two-dimensional array of characters which represents all or part of the terminal screen. A window can be as big as the terminal screen or any smaller size down to a single character. The header file supplies two default windows, (standard screen) and (current screen) for all programs using routines. The window is the size of the current terminal screen. The window is not normally accessed directly by the screen-management program; changes are made to the appropriate window and then the routine is called. The screen program keeps track of what is on the physical screen and what is on When is called, it compares the two screen images and then sends a stream of characters to the terminal to make the physical screen look like The header file defines to be of the type This is a pointer to a C structure which includes the starting position of the window on the screen and the window size. Some routines are designed to work with a A pad is a type of window whose size is not restricted by the size of the screen. Use a pad when you only need part of a window on the screen at any one time, for example when running a spreadsheet application. Other windows can be created with and used instead of for maintaining several different screen images, for example, one window can control input/output and another can display error messages. The routine creates subwindows within windows. When windows overlap, the contents of the current screen show the most recently refreshed window. Among the most basic routines are and These routines are used to move the cursor around and to add characters to the default window, All data is manipulated using the routines provided by the library. You should not use routines or system calls from other libraries in a program as they may cause undesirable results when you run the program. Using Curses The library has three types of routines; Main routines, TERMINFO routines and TERMCAP compatibility routines The routines are a group of routines within the library which provide a database containing descriptions of many terminals that can be used with programs. The termcap compatibility routines are provided as a conversion aid for programs using termcap. Most screen handling can be achieved using the Main routines. The following hints should help you make the most of the screen-handling routines. The header file must always be included whenever functions are used in a program. Note that the header file includes to enable the terminal to use the features provided by ULTRIX. All the manual definitions assume that has been included in the code. The header file defines global variables and data structures, and defines several of the routines as macros. The integer variables and are defined so that when a program is run on a particular terminal, assigns the vertical and horizontal dimensions of the terminal screen to these variables. A program must start by calling the routine to allocate memory space for the windows. It should only be called once in a program, as it can overflow core memory if it is called repeatedly. The routine is used to exit from the screen-handling routines. Most interactive screen-oriented programs need character-at-a-time input without echoing. To achieve this, you should call: nonl(); cbreak(); noecho(); immediately after calling All routines that move the cursor, move it relative to the home position in the upper left corner of the screen. The coordinate at this position is (1,1). Note that the vertical coordinate is given first and the horizontal coordinate is given second. The -1 in the example program takes the home position into account to place the cursor on the centre line of the terminal screen. The example program displays MIDSCREEN in the centre of the screen. Use the routine after changing a screen to make the terminal screen look like Example Program (R) #include <cursesX.h> main () { initscr(); /*initialize terminal settings, data ** structures and variables*/ move(LINES/2 -1, COLS/2 -4); addstr("MID"); refresh(); /* send output to update terminal ** screen */ addstr("SCREEN"); refresh(); /* send more output to terminal ** screen */ endwin(); /*restore all terminal settings */ } Main Routines Routines listed here can be called when using the library. Routines that are preceded by a w affect a specified window, those preceded by a p affect a specified pad. All other routines affect the default window Windows are specified by a numeric argument, for example: (win) where win is the specified window. addch(ch) Add a character to stdscr (like putchar wraps to next line at end of line) addstr(str) Call addch with each character in str attroff(attrs) Turn off named attributes attron(attrs) Turn on named attributes attrset(attrs) Set current attributes to attrs baudrate() Display current terminal speed beep() Sound beep on terminal box(win, vert, hor) Draw a box around edges of win, vert and hor are characters to use for vertical and horizontal edges of box clear() Clear stdscr clearok(win, bf) Clear screen before next redraw of win clrtobot() Clear to bottom of stdscr clrtoeol() Clear to end of line on stdscr cbreak() Set cbreak mode delay_output(ms) Insert ms millisecond pause in output delch() Delete a character deleteln() Delete a line delwin(win) Delete win doupdate() Update screen from all wnoutrefresh echo() Set echo mode endwin() End window modes erase() Erase stdscr erasechar() Return user's erase character fixterm() Restore tty to in ``curses'' state flash() Flash screen or beep flushinp() Throw away any typeahead getch() Get a character from tty getstr(str) Get a string through stdscr gettmode() Establish current tty modes getyx(win, y, x) Get (y, x) coordinates has_ic() True if terminal can do insert character has_il() True if terminal can do insert line idlok(win, bf) Use terminal's insert/delete line if bf != 0 inch() Get character at current (y, x) coordinates initscr() Initialize screens insch(c) Insert a character insertln() Insert a line intrflush(win, bf) Interrupt flush output if bf is TRUE keypad(win, bf) Enable keypad input killchar() Return current user's kill character leaveok(win, flag) Leave cursor anywhere after refresh if flag!=0 for win. Otherwise cursor must be left at current position longname() Return verbose name of terminal meta(win, flag) Allow meta characters on input if flag != 0 move(y, x) Move to (y, x) on stdscr NOTE: The following routines prefixed with mv require and coordinates to move to, before performing the same functions as the standard rou- tines. As an example, performs the same function as and coordinates must be supplied first. The routines prefixed with mvw also require a window or pad argument. mvaddch(y, x, ch) mvaddstr(y, x, str) mvcur(oldrow, oldcol, newrow, low level cursor motion newcol) mvdelch(y, x) mvgetch(y, x) mvgetstr(y, x) mvinch(y, x) mvinsch(y, x, c) mvprintw(y, x, fmt, args) mvscanw(y, x, fmt, args) mvwaddch(win, y, x, ch) mvwaddstr(win, y, x, str) mvwdelch(win, y, x) mvwgetch(win, y, x) mvwgetstr(win, y, x) mvwin(win, by, bx) mvwinch(win, y, x) mvwinsch(win, y, x, c) mvwprintw(win, y, x, fmt, args) mvwscanw(win, y, x, fmt, args) newpad(nlines, ncols) Create a new pad with given dimensions newterm(type, fd) Set up new terminal of given type to output on fd newwin(lines, cols, Create a new window begin_y, begin_x) nl() Set newline mapping nocbreak() Unset cbreak mode nodelay(win, bf) Enable nodelay input mode through getch noecho() Unset echo mode nonl() Unset newline mapping noraw() Unset raw mode overlay(win1, win2) Overlay win1 on win2 overwrite(win1, win2) Overwrite win1 on top of win2 pnoutrefresh(pad, pminrow, Like prefresh but with no output pmincol, sminrow, smincol, until doupdate called smaxrow, smaxcol) prefresh(pad, pminrow, Refresh from pad starting with given upper pmincol, sminrow, smincol, left corner of pad with output to smaxrow, smaxcol) given portion of screen printw(fmt, arg1, arg2, ...) printf on stdscr raw() Set raw mode refresh() Make current screen look like stdscr resetterm() Set tty modes to ``out of curses'' state resetty() Reset tty flags to stored value saveterm() Save current modes as ``in curses'' state savetty() Store current tty flags scanw(fmt, arg1, arg2, ...) scanf through stdscr scroll(win) Scroll win one line scrollok(win, flag) Allow terminal to scroll if flag != 0 set_term(new) Switch between different terminals setscrreg(t, b) Set user scrolling region to lines t through b setupterm(term, filenum, errret) Low level terminal setup standend() Clear standout mode attribute standout() Set standout mode attribute subwin(win, lines, cols, Create a subwindow begin_y, begin_x) touchwin(win) "change" all of win traceoff() Turn off debugging trace output traceon() Turn on debugging trace output typeahead(fd) Use file descriptor fd to check typeahead unctrl(ch) Produce printable version of ch waddch(win, ch) Add character to win waddstr(win, str) Add string to win wattroff(win, attrs) Turn off attrs in win wattron(win, attrs) Turn on attrs in win wattrset(win, attrs) Set attrs in win to attrs wclear(win) Clear win wclrtobot(win) Clear to bottom of win wclrtoeol(win) Clear to end of line on win wdelch(win, c) Delete char from win wdeleteln(win) Delete line from win werase(win) Erase win wgetch(win) Get a character through win wgetstr(win, str) Get a string through win winch(win) Get character at current (y, x) in win winsch(win, c) Insert char into win winsertln(win) Insert line into win wmove(win, y, x) Set current (y, x) coordinates on win wnoutrefresh(win) Refresh but no screen output wprintw(win, fmt, printf on win arg1, arg2, ...) wrefresh(win) Make screen look like win wscanw(win, fmt, scanf through win arg1, arg2, ...) wsetscrreg(win, t, b) Set scrolling region of win wstandend(win) Clear standout attribute in win wstandout(win) Set standout attribute in win Caution The plotting library and the library both use the names and The versions are macros. If you need both libraries, put the code in a differ- ent source file to the code, and/or and in the code. TERMINFO Level Routines If the environment variable TERMINFO is defined, any program using will check for a local terminal definition before checking in the stan- dard libraries. For example, if the standard place is set to vt100, the compiled file will normally be found in The v is copied from the first letter of vt100 to avoid creating huge directories. However, if TERMINFO is set to will first check and if that fails, will then check This is useful for developing experimental definitions or when there is no write permission for These routines should be called by programs that need to deal directly with the database, but as this is a low level interface, it is not recommended. Initially, the routine should be called. This will define the set of terminal-dependent variables defined in The include files and should be included to get the definitions for these strings, numbers, and flags. Parameterized strings should be passed through to instantiate them. All terminfo strings (including the output of should be printed with or Before exiting, should be called to restore the tty modes. Programs which want shell escapes or suspending can call before the shell is called and after returning from the shell. fixterm() Restore tty modes for terminfo use (called by setupterm) resetterm() Reset tty modes to state before program entry setupterm(term, fd, rc) Read in database. Terminal type is the character string term, all output is to ULTRIX System file descriptor fd. A status value is returned in the integer pointed to by rc: 1 is normal. The simplest call would be setupterm(0, 1, 0) which uses all defaults tparm(str, p1, p2, ..., p9) Instantiate string str with parms pi tputs(str, affcnt, putc) Apply padding info to string str affcnt is the number of lines affected, or 1 if not applicable. Putc is a putchar-like function to which the characters are passed, one at a time putp(str) A function that calls tputs (str, 1, putchar) vidputs(attrs, putc) Output the string to put terminal in video attribute mode attrs, which is any combination of the attributes listed below Chars are passed to putchar-like function putc vidattr(attrs) Like vidputs but outputs through putchar Termcap Compatibility Routines The following routines were included as a conversion aid for programs that use termcap. Their parameters are the same as for termcap. They are emulated using the database. DO NOT use these routines in new programs. tgetent(bp, name) Look up termcap entry for name tgetflag(id) Get boolean entry for id tgetnum(id) Get numeric entry for id tgetstr(id, area) Get string entry for id tgoto(cap, col, row) Apply parms to given cap tputs(cap, affcnt, fn) Apply padding to cap calling fn as putchar As an aid to compatibility, the object module has been provided in This module should be linked into an application before resolving against the library. If your application contains references such as then recompile using cc [options] files /usr/lib/termcap.o -lcursesX [libs] Errors No errors are defined for the functions. Return Values For most routines, the value is returned if a routine is properly completed and the value is returned if some error occurs. See Also tic(1), ioctl(2), getenv(3), printf(3s), putchar(3s), scanf(3s), plot(3x), termcap(5), terminfo(5) Guide to X/Open curses Screen Handling intro(3cur)