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
	   definition 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:

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

       bool	       Boolean data type.

       cchar_t	       A type that refers to a string consisting of a  spacing
		       wide  character,	 up to	5 non-spacing wide characters,
		       and zero	or  more  attributes  of  any  type.  See  At-
		       tributes,  Color	 Pairs,	and Renditions.	A null cchar_t
		       object terminates arrays	of cchar_t objects.

       chtype	       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 and COLOR_PAIR(3XCURSES)

       SCREEN	       An  opaque  data	type associated	with a terminal's dis-
		       play screen.

       TERMINAL	       An opaque data type associated with a terminal. It con-
		       tains information about the terminal's capabilities (as
		       defined by terminfo), the terminal modes,  and  current
		       state of	input/output operations.

       wchar_t	       An integral data	type whose values represent wide char-

       WINDOW	       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.

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

       Window	       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:

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

       Derived Window	       A subwindow whose position is defined  relative
			       to the parent 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.

       Terminal		       A terminal is the input and output device which
			       character-based	applications  use  to interact
			       with the	user. The TERMINAL data	type is	 asso-
			       ciated 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  characters.    The	 remainder of that line	is filled with
	    the	background character. If scrolling is disabled,	X/Open	Curses
	    truncates  any character 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 charac-
	    ters  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:

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

       Carriage	Return	       Moves the cursor	to the beginning of  the  cur-
			       rent line. If the cursor	was already at the be-
			       ginning of the line, it remains there. All sub-
			       sequent	characters  are	 added	or inserted at
			       this point.

       Newline		       When adding characters, X/Open Curses fills the
			       remainder of the	line with the background char-
			       acter (effectively truncating the newline)  and
			       scrolls	the   window as	described earlier. All
			       subsequent 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 ear-
			       lier. All subsequent characters 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  charac-
			       ter 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   processing,	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  win-
			       dow. Functions that retrieve text from the win-
			       dow will	retrieve the  converted	 notation  not
			       the original.

       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() func-
			       tions will not return until a complete line has
			       been  read  by  the  terminal  driver, at which
			       point only the requested	number of  bytes/char-
			       acters are returned.  The rest of the line unit
			       remains unread until  subsequent	 call  to  the
			       getch() or getnstr() functions.

			       The   functions	 nocbreak(3XCURSES)   and  no-
			       raw(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 applica-
			       tions 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 applica-
			       tion's responsibility to	handle line editing.
				 It is unknown whether the  signal  characters
			       (SIGINTR,  SIGQUIT,  SIGSUSP)  and flow control
			       characters  (SIGSTART,  SIGSTOP)	 are  enabled.
			       To ensure that they are,	call the noraw() func-
			       tion first, then	call the cbreak() function.

       halfdelay Mode	       This is the same	as the cbreak()	 mode  with  a
			       timeout.	  The terminal 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	 over-
			       rides  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-

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |Unsafe			   |

       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), attributes(5), environ(5), standards(5), termio(7I)

SunOS 5.10			  5 Jun	2002		      curses(3XCURSES)


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

home | help