---
name: "curs_add_wch"
section: "3x"
platform: "macos"
package: "ncurses"
version: "79"
release: "macOS 26.5"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/curs_add_wch/3x"
---

# curs\_add\_wch(3x)

add a complex character and rendition to a curses window, then advance the cursor

## NAME

**add\_wch**, **wadd\_wch**, **mvadd\_wch**, **mvwadd\_wch**, **echo\_wchar**, **wecho\_wchar** - add a complex character and rendition to a **curses** window, then advance the cursor

## SYNOPSIS

**#include \<curses.h\>**

**int add\_wch( const cchar\_t \**wch* );**\
 **int wadd\_wch( WINDOW \**win*, const cchar\_t \**wch* );**\
 **int mvadd\_wch( int *y*, int *x*, const cchar\_t \**wch* );**\
 **int mvwadd\_wch( WINDOW \**win*, int *y*, int *x*, const cchar\_t \**wch* );**\
 **int echo\_wchar( const cchar\_t \**wch* );**\
 **int wecho\_wchar( WINDOW \**win*, const cchar\_t \**wch* );**\

## DESCRIPTION

### add\_wch

The **add\_wch**, **wadd\_wch**, **mvadd\_wch**, and **mvwadd\_wch** functions put the complex character *wch* into the given window at its current position, which is then advanced. These functions perform wrapping and special-character processing as follows:

- •

  If *wch* refers to a spacing character, then any previous character at that location is removed. A new character specified by *wch* is placed at that location with rendition specified by *wch*. The cursor then advances to the next spacing character on the screen.

- •

  If *wch* refers to a non-spacing character, all previous characters at that location are preserved. The non-spacing characters of *wch* are added to the spacing complex character, and the rendition specified by *wch* is ignored.

- •

  If the character part of *wch* is a tab, newline, backspace or other control character, the window is updated and the cursor moves as if **addch** were called.

### echo\_wchar

The **echo\_wchar** function is functionally equivalent to a call to **add\_wch** followed by a call to **refresh**. Similarly, the **wecho\_wchar** is functionally equivalent to a call to **wadd\_wch** followed by a call to **wrefresh**. The knowledge that only a single character is being output is taken into consideration and, for non-control characters, a considerable performance gain might be seen by using the \***echo**\* functions instead of their equivalents.

### Line Graphics

Like **addch**(3X), **addch\_wch** accepts symbols which make it simple to draw lines and other frequently used special characters. These symbols correspond to the same VT100 line-drawing set as **addch**(3X).

| | | | |
| --- | --- | --- | --- |
| *Name* | *Unicode* | *Default* | *Description* |
|
| WACS\_BOARD | 0x2592 | # | board of squares |
| WACS\_BTEE | 0x2534 | + | bottom tee |
| WACS\_BULLET | 0x00b7 | o | bullet |
| WACS\_CKBOARD | 0x2592 | : | checker board (stipple) |
| WACS\_DARROW | 0x2193 | v | arrow pointing down |
| WACS\_DEGREE | 0x00b0 |  | degree symbol |
| WACS\_DIAMOND | 0x25c6 | + | diamond |
| WACS\_GEQUAL | 0x2265 | \> | greater-than-or-equal-to |
| WACS\_HLINE | 0x2500 | - | horizontal line |
| WACS\_LANTERN | 0x2603 | # | lantern symbol |
| WACS\_LARROW | 0x2190 | \< | arrow pointing left |
| WACS\_LEQUAL | 0x2264 | \< | less-than-or-equal-to |
| WACS\_LLCORNER | 0x2514 | + | lower left-hand corner |
| WACS\_LRCORNER | 0x2518 | + | lower right-hand corner |
| WACS\_LTEE | 0x2524 | + | left tee |
| WACS\_NEQUAL | 0x2260 | ! | not-equal |
| WACS\_PI | 0x03c0 | \* | greek pi |
| WACS\_PLMINUS | 0x00b1 | # | plus/minus |
| WACS\_PLUS | 0x253c | + | plus |
| WACS\_RARROW | 0x2192 | \> | arrow pointing right |
| WACS\_RTEE | 0x251c | + | right tee |
| WACS\_S1 | 0x23ba | - | scan line 1 |
| WACS\_S3 | 0x23bb | - | scan line 3 |
| WACS\_S7 | 0x23bc | - | scan line 7 |
| WACS\_S9 | 0x23bd | \_ | scan line 9 |
| WACS\_STERLING | 0x00a3 | f | pound-sterling symbol |
| WACS\_TTEE | 0x252c | + | top tee |
| WACS\_UARROW | 0x2191 | ^ | arrow pointing up |
| WACS\_ULCORNER | 0x250c | + | upper left-hand corner |
| WACS\_URCORNER | 0x2510 | + | upper right-hand corner |
| WACS\_VLINE | 0x2502 | \| | vertical line |

The wide-character configuration of ncurses also defines symbols for thick- and double-lines:

| | | | |
| --- | --- | --- | --- |
| *Name* | *Unicode* | *Default* | *Description* |
|
| WACS\_T\_LLCORNER | 0x2517 | + | thick lower left corner |
| WACS\_T\_URCORNER | 0x2513 | + | thick upper right corner |
| WACS\_T\_LRCORNER | 0x251b | + | thick lower right corner |
| WACS\_T\_LTEE | 0x252b | + | thick tee pointing right |
| WACS\_T\_RTEE | 0x2523 | + | thick tee pointing left |
| WACS\_T\_BTEE | 0x253b | + | thick tee pointing up |
| WACS\_T\_TTEE | 0x2533 | + | thick tee pointing down |
| WACS\_T\_HLINE | 0x2501 | - | thick horizontal line |
| WACS\_T\_VLINE | 0x2503 | \| | thick vertical line |
| WACS\_T\_PLUS | 0x254b | + | thick large plus or crossover |
| WACS\_D\_ULCORNER | 0x2554 | + | double upper left corner |
| WACS\_D\_LLCORNER | 0x255a | + | double lower left corner |
| WACS\_D\_URCORNER | 0x2557 | + | double upper right corner |
| WACS\_D\_LRCORNER | 0x255d | + | double lower right corner |
| WACS\_D\_RTEE | 0x2563 | + | double tee pointing left |
| WACS\_D\_LTEE | 0x2560 | + | double tee pointing right |
| WACS\_D\_BTEE | 0x2569 | + | double tee pointing up |
| WACS\_D\_TTEE | 0x2566 | + | double tee pointing down |
| WACS\_D\_HLINE | 0x2550 | - | double horizontal line |
| WACS\_D\_VLINE | 0x2551 | \| | double vertical line |
| WACS\_D\_PLUS | 0x256c | + | double large plus or crossover |

## RETURN VALUE

All routines return the integer **ERR** upon failure and **OK** on success.

Functions with a "mv" prefix first perform a cursor movement using **wmove**, and return an error if the position is outside the window, or if the window pointer is null.

## NOTES

Note that **add\_wch**, **mvadd\_wch**, **mvwadd\_wch**, and **echo\_wchar** may be macros.

## PORTABILITY

All of these functions are described in the XSI Curses standard, Issue 4. The defaults specified for line-drawing characters apply in the POSIX locale.

X/Open Curses makes it clear that the WACS\_ symbols should be defined as a pointer to **cchar\_t** data, e.g., in the discussion of **border\_set**. A few implementations are problematic:

- •

  NetBSD curses defines the symbols as a **wchar\_t** within a **cchar\_t**.

- •

  HPUX curses equates some of the *ACS\_* symbols to the analogous *WACS\_* symbols as if the *ACS\_* symbols were wide characters. The misdefined symbols are the arrows and other symbols which are not used for line-drawing.

X/Open Curses does not define symbols for thick- or double-lines. SVr4 curses implementations defined their line-drawing symbols in terms of intermediate symbols. This implementation extends those symbols, providing new definitions which are not in the SVr4 implementations.

## SEE ALSO

**curses**(3X), **curs\_addch**(3X), **curs\_attr**(3X), **curs\_clear**(3X), **curs\_outopts**(3X), **curs\_refresh**(3X), [**putwc**(3)](/putwc/3.md)