addch, mvaddch, mvwaddch, or waddch Subroutine

Purpose

Adds a single-byte character and rendition to a window and advances the cursor.

Library

Curses Library (libcurses.a)

Syntax

#include <curses.h>

int addch(const chtype ch); 

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

int mvwaddch(WINDOW *in,
const chtype ch);

int waddch(WINDOW *win,
const chtype ch);

Description

The addch, waddch, mvaddch, and mvwaddch subroutines add a character to a window at the logical cursor location. After adding the character, curses advances the position of the cursor one character. At the right margin, an automatic new line is performed.

The addch subroutine adds the character to the stdscr at the current logical cursor location. To add a character to a user-defined window, use the waddch and mvwaddch subroutines. The mvaddch and mvwaddch subroutines move the logical cursor before adding a character.

If you add a character to the bottom of a scrolling region, curses automatically scrolls the region up one line from the bottom of the scrolling region if scrollok is enabled. If the character to add is a tab, new-line, or backspace character, curses moves the cursor appropriately in the window to reflect the addition. Tabs are set at every eighth column. If the character is a new-line, curses first uses the wclrtoeol subroutine to erase the current line from the logical cursor position to the end of the line before moving the cursor.

You can also use the addch subroutines to add control characters to a window. Control characters are drawn in the ^X notation.

Adding Video Attributes and Text

Because the Char parameter is an integer, not a character, you can combine video attributes with a character by ORing them into the parameter. The video attributes are also set. With this capability you can copy text and video attributes from one location to another using the inch and addch subroutines.

Parameters

Return Values

Upon successful completion, these subroutines return OK. Otherwise, they return ERR.

Examples

1. To add the character H represented by variable x to stdscr at the current cursor location, enter:

   chtype x;
   x='H';
   addch(x);

2. To add the x character to stdscr at the coordinates y = 10, x = 5, enter:

   mvaddch(10, 5, 'x');

3. To add the x character to the user-defined window my_window at the coordinates y = 10, x = 5, enter:

   WINDOW *my_window;
   mvwaddch(my_window, 10, 5, 'x');

4. To add the x character to the user-defined window my_window at the current cursor location, enter:

   WINDOW *my_window;
   waddch(my_window, 'x');

5. To add the character x in standout mode, enter:

   waddch(my_window, 'x' | A_STANDOUT);

   This allows 'x' to be highlighted, but leaves the rest of the window alone.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The inch, winch, mvinch, or mvwinch subroutines, wclrtoeol subroutine.

Curses Overview for Programming, List of Curses Subroutines, Manipulating Characters with Curses in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.