Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
curses(3XCURSES)	X/Open Curses Library Functions	      curses(3XCURSES)

       curses -	introduction and overview of X/Open Curses

       The  Curses screen management package conforms fully with Issue 4, Ver-
       sion 2 of the  X/Open Curses specification.   It	provides a set of  in-
       ternationalized	functions and macros for creating and  modifying input
       and output to a terminal	screen.	 This includes functions for  creating
       windows,	 highlighting  text, writing to	 the screen, reading from user
       input, and moving the cursor.

       X/Open Curses is	a terminal-independent	package,  providing  a	common
       user interface to a variety of terminal types.  Its portability	is fa-
       cilitated by the	Terminfo database which	contains a  compiled   defini-
       tion  of	 each terminal type.  By referring to the database information
       X/Open Curses gains access to low-level details about individual	termi-

       X/Open  Curses tailors its activities to	the terminal type specified by
       the TERM	environment variable.  The  TERM environment  variable may  be
       set in the Korn Shell (see ksh(1)) by typing:

       export TERM=terminal_name
       To  set	environment  variables	using other command line interfaces or
       shells, see the environ(5) manual page.

       Three additional	environment variables are useful, and can  be  set  in
       the Korn	Shell:

       1. If you have an alternate Terminfo database containing	terminal types
	  that	are   not   available	in   the   system   default   database
	  /usr/share/lib/terminfo,  you	 can specify the  TERMINFO environment
	  variable to point to this alternate database:

	  export TERMINFO=path

	  This path specifies the location of the alternate compiled  Terminfo
	  database whose structure consists of directory names 0 to 9 and a to
	  z  (which represent the first	letter of the compiled terminal	 defi-
	  nition file  name).

	  The  alternate  database  specified by  TERMINFO is  examined	before
	  the system default database.	If the	terminal  type	 specified  by
	  TERM	cannot	be found in either database, the default terminal type
	  dumb is assumed.

       2. To specify a window width smaller than your screen width (for	 exam-
	  ple,	in situations where your communications	line is	slow), set the
	  COLUMNS  environment	variable to the	number of vertical columns you
	  want between the left	and  right margins:

	  export COLUMNS=number

	  The number of	columns	may be set to a	number smaller than the	screen
	  size;	however, if set	larger than the	screen or  window  width,  the
	  results are undefined.

	  The  value set using this environment	variable takes precedence over
	  the  value normally used for the terminal.

       3. To specify a window height smaller than your current	screen	height
	  (for example,	in situations where your communications	line is	slow),
	  override the	LINES environment variable by setting it to a  smaller
	  number of  horizontal	lines:

	  export LINES=number

	  The  number  of lines	may be set to a	number smaller than the	screen
	  height; however, if set larger than the screen or window height, the
	  results are undefined.

	  The  value set using this environment	variable takes precedence over
	  the value normally used for the terminal.

   Data	Types
       X/Open Curses defines the following data	types:

	     An	integral type that holds an OR-ed set of attributes.  The  at-
	     tributes acceptable are those which begin with the	WA_ prefix .

       bool  Boolean data type.

	     A type that refers	to a string consisting of a spacing wide char-
	     acter, up to  5 non-spacing wide characters, and zero or more at-
	     tributes  of  any	type.  See Attributes, Color Pairs, and	Rendi-
	     tions. A null cchar_t object terminates  arrays  of  cchar_t  ob-

	     An	 integral  type	whose values are formed	by OR-ing an "unsigned
	     char" with	a color	pair.  and with	zero or	more  attributes.  The
	     attributes	 acceptable  are  those	which begin with the A_	prefix

	     An	opaque data type associated with a terminal's display screen.

	     An	opaque data type associated with a terminal. It	 contains  in-
	     formation	about  the terminal's capabilities (as defined by ter-
	     minfo), the terminal modes, and current state of input/output op-

	     An	integral data type whose values	represent wide characters.

	     An	opaque data type associated with a window.

   Screens, Windows, and Terminals
       The X/Open Curses manual	pages refer at various points to screens, win-
       dows (also subwindows, derived windows, and pads), and  terminals.  The
       following list defines each of these terms.

	     A screen is a terminal's physical output device.  The SCREEN data
	     type is associated	with a terminal.

	     Window objects are	two-dimensional	arrays of characters and their
	     renditions. X/Open	Curses provides	stdscr,	a default window which
	     is	 the  size  of	of  the	 terminal  screen.  You	 can  use  the
	     newwin(3XCURSES) function to create others.

       To  refer  to  a	 window,  use  a variable declared as WINDOW *.	X/Open
       Curses includes both functions that modify  stdscr,  and	 more  general
       versions	that let you specify a window.

       There are three sub-types of windows:

		    A window which has been created within another window (the
		    parent window) and whose position has been specified  with
		    absolute screen coordinates. The derwin(3XCURSES) and sub-
		    win(3XCURSES) functions can	be used	to create  subwindows.

	      Derived Window
		    A subwindow	whose position is defined relative to the par-
		    ent	window's  coordinates rather than in absolute terms.

	      Pad   A  special	type  of  window  that	can be larger than the
		    screen. For	more information,  see	the   newpad(3XCURSES)
		    man	page.

		    A terminal is the input and	output device which character-
		    based applications use to interact with the	user. The TER-
		    MINAL data type is associated with such a device.

   Attributes, Color Pairs, and	Renditions
       A character's rendition consists	of its attributes (such	as underlining
       or reverse video) and its color pair  (the  foreground  and  background
       colors).	   When	   using    waddstr(3XCURSES),	  waddchstr(3XCURSES),
       wprintw(3XCURSES), winsch(3XCURSES), and	so on, the window's  rendition
       is  combined  with that character's renditions. The window rendition is
       the  attributes	and  color  set	 using	the    attroff(3XCURSES)   and
       attr_off(3XCURSES) sets of functions. The window's background character
       and  rendition  are  set	 with  the   bkgdset(3XCURSES)	 and   bkgrnd-
       set(3XCURSES) sets of functions.

       When  spaces  are  written  to the screen, the background character and
       window  rendition replace the space. For	 example,  if  the  background
       rendition and character is  A_UNDERLINE|'*', text written to the	window
       appears underlined and the spaces appear	as underlined asterisks.

       Each character written retains the rendition that it has	obtained. This
       allows  the character to	be copied "as is" to or	from a window with the
       addchstr(3XCURSES) or inch(3XCURSES) functions.

   A_ Constant Values for Attributes
       You can specify Attributes, Color Pairs,	and Renditions attributes  us-
       ing  the	 constants listed in the tables	below. The following constants
       modify objects of type chtype:

       |Constant		      Description		      |
       |A_ALTCHARSET		      Alternate	character set	      |
       |A_ATTRIBUTES		      Bit-mask to extract attributes  |
       |A_BLINK			      Blinking			      |
       |A_BOLD			      Bold			      |
       |A_CHARTEXT		      Bit-mask to extract a character |
       |A_COLOR			      Bit-mask to extract  color-pair |
       |			      information		      |
       |A_DIM			      Half-bright		      |
       |A_INVIS			      Invisible			      |
       |A_PROTECT		      Protected			      |
       |A_REVERSE		      Reverse video		      |
       |A_STANDOUT		      Highlights specific to terminal |
       |A_UNDERLINE		      Underline			      |

   WA_ Constant	Values for Attributes
       The following constants modify objects of type attr_t:

       |Constant		      Description		      |
       |WA_ALTCHARSET		      Alternate	character set	      |
       |WA_ATTRIBUTES		      Attribute	mask		      |
       |WA_BLINK		      Blinking			      |
       |WA_BOLD			      Bold			      |
       |WA_DIM			      Half-bright		      |
       |WA_HORIZONTAL		      Horizontal highlight	      |
       |WA_INVIS		      Invisible			      |
       |WA_LEFT			      Left highlist		      |
       |WA_LOW			      Low highlist		      |
       |WA_PROTECT		      Protected			      |
       |WA_REVERSE		      Reverse video		      |
       |WA_RIGHT		      Right highlight		      |
       |WA_STANDOUT		      Highlights specific to terminal |
       |WA_TOP			      Top highlight		      |
       |WA_UNDERLINE		      Underline			      |
       |WA_VERTICAL		      Vertical highlight	      |

   Color Macros
       Colors  always  appear  in pairs; the foreground	color of the character
       itself and the background color of the field on which it	is  displayed.
       The following color macros are defined:

       |Macro			      Description		   |
       |COLOR_BLACK		      Black			   |
       |COLOR_BLUE		      Blue			   |
       |COLOR_GREEN		      Green			   |
       |COLOR_CYAN		      Cyan			   |
       |COLOR_RED		      Red			   |
       |COLOR_MAGENTA		      Magenta			   |
       |COLOR_YELLOW		      Yellow			   |
       |COLOR_WHITE		      White			   |

       Together,  a character's	attributes and its color pair form the charac-
       ter's rendition.	A character's rendition	moves with the character  dur-
       ing  any	 scrolling or insert/delete operations.	If your	terminal lacks
       support for the specified rendition, X/Open Curses  may	 substitute  a
       different rendition.

       The  COLOR_PAIR(3XCURSES)  function  modifies  a	 chtype	 object.   The
       PAIR_NUMBER(3XCURSES) function extracts the color pair  from  a	chtype

   Functions for Modifying a Window's Color
       The following functions modify a	window's color:

       |Function		      Description		     |
       |attr_set(), wattr_set()	      Change the window's rendition. |
       |color_set(), wcolor_set()     Set the window's color	     |

   Non-Spacing Characters
       When  the wcwidth(3C) function returns a	width of zero for a character,
       that character is called	a non-spacing character.  Non-spacing  charac-
       ters  can be written to a window. Each non-spacing character is associ-
       ated with a spacing character (that is, one which does not have a width
       of  zero) and modifies that character. You cannot address a non-spacing
       character directly. Whenever you	perform	an X/Open Curses operation  on
       the  associated character,  you are implicitly addressing the non-spac-
       ing character.

       Non-spacing characters do not have a rendition. For functions that  use
       wide  characters	 and  a	rendition, X/Open Curses ignores any rendition
       specified for non-spacing characters. Multi-column characters have  one
       rendition that applies to all columns spanned.

   Complex Characters
       The cchar_t date	type represents	a complex character. A complex charac-
       ter may contain a spacing character, its	associated non-spacing charac-
       ters, and its rendition.	This implementation of complex characters sup-
       ports up	to 5 non-spacing characters for	each spacing character.

       When a cchar_t object representing a non-spacing	complex	 character  is
       written to the screen, its rendition is not used, but rather it becomes
       associated with the rendition of	the existing character at  that	 loca-
       tion.  The  setcchar(3XCURSES)  function	 initializes an	object of type
       cchar_t.	The getcchar(3XCURSES) function	extracts  the  contents	 of  a
       cchar_t	object.

   Display Operations
       In  adding internationalization support to X/Open Curses, every attempt
       was made	to minimize the	number of changes  to  the  historical	CURSES
       package.	 This enables programs written to use the historical implemen-
       tation of CURSES	to use the internationalized version with little or no
       modification. The following rules apply to the internationalized	X/Open
       Curses package:

	  o  The cursor	can be placed anywhere in  the	window.	   Window  and
	     screen origins are	(0,0).

	  o  A	multi-column character cannot be displayed in the last column,
	     because the character would appear	truncated. Instead, the	 back-
	     ground  character	is displayed in	the last column	and the	multi-
	     column character appears at the beginning of the next line.  This
	     is	called wrapping.

       If  the	original  line	is  the	 last  line  in	 the scroll region and
       scrolling is  enabled, X/Open Curses moves the contents of each line in
       the  region  to	the  previous  line.   The first line of the region is
       lost. The last line of the scrolling region contains any	wrapped	 char-
       acters.	  The  remainder  of  that  line is filled with	the background
       character. If scrolling is disabled, X/Open Curses truncates any	 char-
       acter that would	extend past the	last column of the screen.

	  o  Overwrites	operate	on screen columns. If displaying a single-col-
	     umn or multi-column character results in overwriting  only	a por-
	     tion  of a	multi-column character or characters, background char-
	     acters  are displayed in place of the non-overwritten portions.

	  o  Insertions	and deletions operate on whole characters. The	cursor
	     is	moved to the first column of the character prior to performing
	     the operation.

   Overlapping Windows
       When windows overlap, it	may be necessary to overwrite only part	 of  a
       multi-column  character.	   As  mentioned  earlier, the non-overwritten
       portions	are replaced with the background character.  This  results  in
       issues  concerning  the	overwrite(3XCURSES),  overlay(3XCURSES), copy-
       win(3XCURSES),  wnoutrefresh(3XCURSES),	and  wrefresh(3XCURSES)	 func-

   Special Characters
       Some functions assign special meanings to certain special characters:

	     Moves  the	 cursor	 one column towards the	beginning of the line.
	     If	the cursor was already at the beginning	of the	line,  it  re-
	     mains  there.  All	subsequent characters are added	or inserted at
	     this point.

       Carriage	Return
	     Moves the cursor to the beginning of the  current	line.  If  the
	     cursor  was  already  at  the  beginning  of the line, it remains
	     there. All	subsequent characters are added	or  inserted  at  this

	     When  adding characters, X/Open Curses fills the remainder	of the
	     line with the background character	 (effectively  truncating  the
	     newline) and scrolls the  window as described earlier. All	subse-
	     quent characters are inserted at the start	of the new line.

	     When inserting characters,	X/Open Curses fills the	 remainder  of
	     the  line	with  the background character (effectively truncating
	     the line),	moves the cursor to  the beginning of a	new line,  and
	     scrolls  the  window as described earlier.	All subsequent charac-
	     ters are placed at	the start of the new line.

       Tab   moves subsequent characters to next horizontal tab	strop. Default
	     tab stops are set at 0, 8,	16, and	so on.

	     When  adding  or  inserting  characters, X/Open Curses inserts or
	     adds the  background character into each column  until  the  next
	     tab  stop	is reached. If there are no remaining tab stops	on the
	     current line, wrapping and	 scrolling occur as described earlier.

       Control Characters
	     When X/Open Curses	functions perform special  character  process-
	     ing,  they	convert	control	characters to the ^X notation, where X
	     is	a single-column	character (uppercase, if it is a  letter)  and
	     writes that  notation to the window. Functions that retrieve text
	     from the window will retrieve  the	 converted  notation  not  the

       X/Open  Curses  displays	 non-printable bytes, that have	their high bit
       set, using the M-X meta notation	where X	is the non-printable byte with
       its high	bit turned off.

   Input Processing
       There  are four input modes possible with X/Open	Curses that affect the
       behavior	of input functions like	getch(3XCURSES)	and getnstr(3XCURSES).

       Line Canonical (Cooked)
	     In	line input mode, the terminal driver handles the input of line
	     units  as	well  as   SIGERASE  and SIGKILL character processing.
	     See termio(7I) for	more information.

	     In	this mode, the getch() and getnstr() functions will not	return
	     until  a  complete	 line has been read by the terminal driver, at
	     which point only the requested number of bytes/characters are re-
	     turned.   The  rest  of the line unit remains unread until	subse-
	     quent call	to the	getch()	or getnstr() functions.

	     The functions nocbreak(3XCURSES) and noraw(3XCURSES) are used  to
	     enter   this   mode.    These  functions  are  described  on  the
	     cbreak(3XCURSES) man page which also details which	termios	 flags
	     are enabled.

	     Of	 the  modes  available,	 this one gives	applications the least
	     amount of control over input.   However, it  is  the  only	 input
	     mode possible on a	block mode terminal.

       cbreak Mode
	     Byte/character  input  provides  a	finer degree of	control.   The
	     terminal driver passes each byte read to the application  without
	     interpreting erase	and kill characters.   It is the application's
	     responsibility to handle line editing.
	       It is unknown whether the signal	characters (SIGINTR,  SIGQUIT,
	     SIGSUSP)  and flow	control	characters (SIGSTART, SIGSTOP) are en-
	     abled.   To ensure	that  they  are,  call	the  noraw()  function
	     first, then call the cbreak() function.

       halfdelay Mode
	     This  is the same as the cbreak() mode with a timeout.   The ter-
	     minal driver waits	for a byte to be received or for  a  timer  to
	     expire,  in which case the	getch()	function either	returns	a byte
	     or	 ERR respectively.   This mode overrides timeouts set  for  an
	     individual	window with the	wtimeout() function.

       raw Mode
	     This mode provides	byte/character input with the most control for
	     an	application. It	is similar to cbreak() mode, but also disables
	     signal  character processing (SIGINTR, SIGSUSP, SIGQUIT) and flow
	     control  processing (SIGSTART, SIGSTOP) so	that  the  application
	     can process  them as it wants.

       These  modes affect all X/Open Curses input.  The default input mode is
       inherited from the parent process when the  application starts up.

       A timeout similar to halfdelay(3XCURSES)	can be applied	to  individual
       windows	(see   timeout(3XCURSES)).  The	 nodelay(3XCURSES) function is
       equivalent to setting wtimeout(3XCURSES)	for a window with a zero time-
       out (non-blocking) or infinite delay (blocking).

       To handle function keys,	keypad(3XCURSES) must be enabled.   When it is
       enabled,	the getch() function returns a KEY_ constant  for  a  uniquely
       encoded key defined for that terminal.	When keypad() is disabled, the
       getch() function	returns	the  individual	bytes composing	 the  function
       key  (see   getch(3XCURSES)  and	 wget_wch(3XCURSES)). By default, key-
       pad() is	disabled.

       When processing function	keys, once the first  byte  is	recognized,  a
       timer is	set for	each subsequent	byte in	the sequence.	If any byte in
       the function key	sequence is not	received before	 the  timer   expires,
       the  bytes  already  received are pushed	into a buffer and the original
       first byte is returned.
	 Subsequent X/Open Curses input	would take bytes from the buffer until
       exhausted,   after which	new input from the terminal will be requested.
       Enabling	and disabling of the function key interbyte timer  is  handled
       by  the notimeout(3XCURSES) function.   By default, notimeout() is dis-
       abled (that is, the timer is used).

       X/Open Curses always disables the terminal  driver's  echo  processing.
       The echo(3XCURSES) and noecho(3XCURSES) functions control X/Open	Curses
       software	 echoing.   When software echoing is  enabled,	X/Open	Curses
       input functions echo printable  characters, control keys, and meta keys
       in the input window at the last cursor  position.   Functions keys  are
       never  echoed.	 When software echoing is disabled, it is the applica-
       tion's responsibility to	 handle	echoing.

       Example 1: Copying Single-Column	Characters Over	Single-Column  Charac-

       In the upcoming examples, some characters have special meanings:

	  o  {,	[, and ( represent the left halves of multi-column characters.
	     },	], and ) represent the corresponding right halves  of the same
	     multi-column characters.

	  o  Alphanumeric  characters  and periods (.) represent single-column

	  o  The number	sign (#) represents the	background character.

       copywin(s, t, 0,	1, 0, 1, 1, 3, 0)

		   s		   t	     ->	    t
	       abcdef	     ......	     .bcd..
	       ghijkl	     ......	     .hij..

	 There are no special problems with this situation.

       Example 2: Copying Multi-column Characters Over	Single-Column  Charac-

       copywin(s, t, 0,	1, 0, 1, 1, 3, 0)

		   s		   t	     ->	    t
	       a[]def	     ......	     .[]d..
	       gh()kl	     ......	     .h()..

	There are no special problems with this	situation.

       Example 3: Copying Single-Column	Characters From	Source Overlaps	Multi-
       column Characters In Target

       copywin(s, t, 0,	1, 0, 1, 1, 3, 0)

		   s		   t	     ->	    t
	       abcdef	     []....	     #bcd..
	       ghijk tol	...().		.hij#.

       Overwriting multi-column	characters in t	has resulted in	 the  #	 back-
       ground  characters  being required to erase the remaining halves	of the
       target's	multi-column characters.

       Example 4: Copy Incomplete Multi-column Characters From Source To  Tar-

       copywin(s, t, 0,	1, 0, 1, 1, 3, 0)

		   s		   t	     ->	    t
	       []cdef	     123456	     []cd56
	       ghi()l	     789012	     7hi()2

       The ] and ( halves of the multi-column characters have been copied from
       the source and expanded in the target outside of	the  specified	target

       Consider	a pop-up dialog	box that contains single-column	characters and
       a base window that contains multi-column	characters and you do the fol-

       save=dupwin(dialog);	/* create backing store	*/
       overwrite(cursor, save);	/* save	region to be overlayed */
       wrefresh(dialog);	/* display dialog */
       wrefresh(save);		/* restore screen image	*/
       delwin(save);		/* release backing store */

       You can use code	similar	to this	to implement generic popup() and  pop-
       down() routines in a variety of CURSES implementations (including   BSD
       UNIX, and UNIX System V). In the	simple case where the base window con-
       tains single-column characters  only, it	would  correctly  restore  the
       image that appeared on the screen before	 the dialog box	was displayed.

       However,	 with  multi-column characters,	the overwrite()	function might
       save a region with incomplete multi-column characters. The wrefresh(di-
       alog)  statement	 results in the	behavior described in example 3	above.
       The behavior described in this example (that is,	example	4) allows  the
       wrefresh(save) statement	to restore the window correctly.

       Example 5: Copying An Incomplete	Multi-column Character To  Region Next
       To Screen Margin	 (Not A	Window Edge)

	Two cases of copying an	incomplete multi-column	character to a	region
       next to a screen	margin follow:

       copywin(s, t, 0,	1, 0, 0, 1, 2, 0)

		   s		   t	     ->	    t
	       []cdef	     123456	     #cd456
	       ghijkl	     789012	     hij012

	The  background	character (#) replaces the ] character that would have
       been copied from	the source, because it is not possible to  expand  the
       multi-column character to its complete form.

       copywin(s, t, 0,	1, 0, 3, 1, 5, 0)

		   s		   t	     ->	    t
	       abcdef	     123456	     123bcd
	       ghi()l	     789012	     789hi#

       This  second  example is	the same as the	first, but with	the right mar-

       ksh(1),	   COLOR_PAIR(3XCURSES),     PAIR_NUMBER(3XCURSES),	addch-
       str(3XCURSES),	       attr_off(3XCURSES),	    attroff(3XCURSES),
       bkgdset(3XCURSES),   bkgrndset(3XCURSES),    cbreak(3XCURSES),	 copy-
       win(3XCURSES),  derwin(3XCURSES),  echo(3XCURSES),  getcchar(3XCURSES),
       getch(3XCURSES),	       getnstr(3XCURSES),	  halfdelay(3XCURSES),
       inch(3XCURSES),	   keypad(3XCURSES),	 libcurses(3XCURSES),	  new-
       pad(3XCURSES), newwin(3XCURSES),	nocbreak(3XCURSES), nodelay(3XCURSES),
       noecho(3XCURSES),     noraw(3XCURSES),	 notimeout(3XCURSES),	 over-
       lay(3XCURSES),	 overwrite(3XCURSES),	  setcchar(3XCURSES),	  sub-
       win(3XCURSES),	       timeout(3XCURSES),	  waddchstr(3XCURSES),
       waddstr(3XCURSES), wcwidth(3C),	wget_wch(3XCURSES),  winsch(3XCURSES),
       wnoutrefresh(3XCURSES),	wprintw(3XCURSES),  wrefresh(3XCURSES),	wtime-
       out(3XCURSES), termio(7I), environ(5)

SunOS 5.9			  23 Oct 2001		      curses(3XCURSES)


Want to link to this manual page? Use this URL:

home | help