addch waddch mvaddch mvwaddch

The addch set of routines is used to add a character (with attributes) to a window.

Syntax

   int addch(chtype ch);

   int waddch(WINDOW *win, chtype ch);

   int mvaddch(int y, int x, chtype ch);

   int mvwaddch(WINDOW *win, int y, int x, chtype ch);

Parameters

ch: The character/attribute pair to be written to the window.
win: A pointer to the window in which the character is to be written.
x: The x (column) coordinate of the character's position in the window.
y: The y (row) coordinate of the character's position in the window.

Return Values

OK: Successful completion.
ERR: An error occurred. An attempt was made to write outside the window boundary or after writing a character, the cursor advanced past the scroll region (and scrollok() is not set).

Description

A window is made up of foreground and background attributes. All characters except space are part of the foreground. The character and its attributes make up a character/attribute pair defined as a chtype. The character is any 16-bit value; the attribute consists of highlighting attributes that affect the appearance of the character on the screen (for example, bold, underline).

Each time that a character, other than a space, is written to a window with waddch(), wprintw(), or waddstr(), a bitwise OR operation is performed between the chtype (foreground character with its attributes), the current foreground attributes of the window, and the current background attributes of the window. The current foreground attributes are set with the wattrset(), wattron(), and wattroff() routines; the current background attributes are set with the wbgdset() routine.

When spaces are written to the screen, the background character and attributes replace the space. For example, if the background attribute and character is



   A_UNDERLINE|'*'

text written to the window appears underlined, and the spaces appear as underlined asterisks.

After the OR operation, each character written retains the new foreground and background attributes that it has obtained. This allows the character to be copied as is to a window with the waddchstr() or insch() routines.

The addch() routine writes a character to the stdscr window at the current cursor position and advances the cursor. The waddch() routine performs an identical action, but writes the character to the window specified by win. The mvaddch() and mvwaddch() routines write the character to the position indicated by the x (column) and y (row) parameters. The mvaddch() routine writes the character to the stdscr window, while mvwaddch() writes the character to the window specified by win.

If the character is a newline, carriage return, backspace, or tab, the cursor is moved appropriately. The cursor is moved to the next tab stop for each tab character (tab stops are eight characters apart). If the character is a control character other than those previously mentioned, the character is written using ^x notation, where x is a printable character. If the character is written to the last character position on a line, a newline is generated automatically. If the character is written to the last character position of a scrolling region and scrollok() is enabled, the scrolling region is scrolled up one line (see wsetscrreg()).

Individual characters can be highlighted by performing a bitwise OR operation between the character and one or more of the constants shown in Table 4-2 “Constant Values for Highlighting Attributes”.

Table 4-2 Constant Values for Highlighting Attributes

Constant	Description
`A_ALTCHARSET`	Alternate character set
`A_ATTRIBUTES`	Attribute mask
`A_BLINK`	Blinking
`A_BOLD`	Bold
`A_CHARTEXT`	Character mask
`A_COLOR`	Color mask
`A_DIM`	Dim
`A_INVIS`	Invisible
`A_NORMAL`	Disable attributes
`A_PROTECT`	No display
`A_REVERSE`	Reverse video
`A_STANDOUT`	Highlights specific to terminal
`A_UNDERLINE`	Underline
`COLOR_PAIR`(`n`)	Color pair number `n`
`PAIR_NUMBER`(`a`)	Pair number for `COLOR_PAIR`(`n`)

The characters shown in Table 4-3 “Constant Values for Characters” are defined as constants in CURSES.

Table 4-3 Constant Values for Characters

Constant	Character	Description
`ACS_VLINE`	\|	Vertical line
`ACS_HLINE`	-	Horizontal line
`ACS_ULCORNER`	+	Upper-left corner
`ACS_URCORNER`	+	Upper-right corner
`ACS_BLCORNER`	+	Bottom-left corner
`ACS_BRCORNER`	+	Bottom-right corner
`ACS_RTEE`	+	Right tee (-\|)
`ACS_LTEE`	+	Left tee (\|-)
`ACS_BTEE`	+	Bottom tee ()
`ACS_TTEE`	+	Top tee (T)
`ACS_CHECK`	!	Check mark
`ACS_PLUS`	+	Plus
`ACS_DIAMOND`	+	Diamond
`ACS_CKBOARD`	:	Checker board
`ACS_DEGREE`	'	Degree sign
`ACS_PLMINUS`	#	Plus/Minus
`ACS_BULLET`	o	Bullet
`ACS_LARROW`	<	Left arrow
`ACS_RARROW`	>	Right arrow
`ACS_DARROW`	v	Down arrow
`ACS_UARROW`	^	Up arrow
`ACS_BOARD`	#	Board of squares
`ACS_LANTERN`	#	Lantern symbol
`ACS_BLOCK`	#	Solid square block




	NOTE: The `addch()`, `mvaddch()`, and `mvwaddch()` routines are macros.

Implementation Considerations

Identical to XPG/3.

Portability

HP-UX, UNIX System V, XPG/3

addch waddch mvaddch mvwaddch

Technical documentation

» Table of Contents

» Index