NAME

inch, winch, mvinch, mvwinch - get a curses character from a window

SYNOPSIS

#include <ncurses/curses.h>

chtype inch(void);
chtype winch(WINDOW *win);
chtype mvinch(int y, int x);
chtype mvwinch(WINDOW *win, int y, int x);

DESCRIPTION

winch returns the curses character, including rendering attributes and color pair identifier, at the cursor position in the window win. Subsection “Video Attributes” of attron(3X) explains how to extract these data from a chtype. ncurses(3X) describes the variants of this function.

RETURN VALUE

Functions prefixed with “mv” first perform cursor movement and fail if the position (y, x) is outside the window boundaries.

These functions do not return an error if the window comprises cells of curses complex characters (that is, they contain characters with codes wider than eight bits, or greater than 255 as an unsigned decimal integer). They instead extract only the low-order eight bits of character data in the cell.

NOTES

inch, mvinch, and mvwinch may be implemented as macros.

PORTABILITY

X/Open Curses, Issue 4 describes these functions. It specifies no error conditions for them.

HISTORY

winch was implemented in the original 4BSD curses library (November 1980). It returned only the character code (as an integer) with the “standout“ attribute bit (the only one it supported) cleared. Because 7-bit ASCII was the only character encoding supported, 4BSD's winch returned a char type.

System V curses (1983) permitted several rendering attributes to be combined with a character in a window. Reflecting this improvement, winch returned an int in SVr3.2 (1988) and switched to chtype in SVr4 (1989).

X/Open Curses does not specify the sizes of the character code or color pair identifier, nor the quantity of rendering attribute bits, in chtype; these are implementation-dependent. ncurses uses eight bits for the character code. An application requiring a wider character type, for instance to handle Unicode, should use the wide-character counterparts of these functions.