Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

intro(3cur) [ultrix man page]

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)
Man Page