You can add characters to a curses window using a keyboard or a curses application. This section describes how you can add, remove, or change characters that appear in a curses window.
Historically, a position on the screen has corresponded to a single stored byte. This correspondence is no longer true for several reasons:
Some character sets define multi-column characters that occupy more than one column position when displayed on the screen.
Writing a character whose width is greater than the width of the destination window is an error.
The curses library provides a number of subroutines that write text changes to a window and mark the area to be updated at the next call to the wrefresh subroutine.
The waddch subroutines overwrite the character at the current logical cursor location with a specified character. After overwriting, the logical cursor is moved one space to the right. If the waddch subroutines are called at the right margin, these subroutines also add an automatic newline character. Additionally, if you call one of these subroutines at the bottom of a scrolling region and scrollok is enabled, the region is scrolled up one line. For example, if you added a new line at the bottom line of a window, the window would scroll up one line.
If the character to add is a tab, newline, 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 newline, 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. The waddch subroutine family is made up of the following:
By using the winch and waddch subroutine families together, you can copy text and video attributes from one place to another. Using the winch subroutine family, you can retrieve a character and its video attributes. You can then use one of the waddch subroutines to add the character and its attributes to another location. For more information, see winch Subroutines.
You can also use the waddch subroutines to add control characters to a window. Control characters are drawn in the ^X notation.
When outputting single, noncontrol characters, there can be significant performance gain to using the wechochar subroutines. These subroutines are functionally equivalent to a call to the corresponding waddchr subroutine followed by the corresponding wrefresh subroutine. The wechochar subroutines include the wechochar subroutine, the echochar macro, and the pechochar subroutine.
Some character sets may contain non-spacing characters. (Nonspacing characters are those, other than the ' \ 0 ' character, for which the wcwidth subroutine returns a width of zero.) The application may write nonspacing characters to a window. Every nonspacing character in a window is associated with a spacing character and modifies the spacing character. Nonspacing characters in a window cannot be addressed separately. A nonspacing character is implicitly addressed whenever a Curses operation affects the spacing character with which the nonspacing character is associated.
Non-spacing characters do not support attributes. For interfaces that use wide characters and attributes, the attributes are ignored if the wide character is a nonspacing character. Multi-column characters have a single set of attributes for all columns. The association of nonspacing characters with spacing characters can be controlled by the application using the wide character interfaces. The wide character string functions provide codeset-dependent association.
The typical effects of a nonspacing character associated with a spacing character called c, are as follows:
Implementations may limit the number of nonspacing characters that can be associated with a spacing character, provided any limit is at least 5.
A complex character is a set of associated characters, which may include a spacing character and may also include any non-spacing characters associated with it. A spacing complex character is a complex character that includes one spacing character and any non-spacing characters associated with it. An example of a code set that has complex characters is ISO/IEC 10646-1:1993.
A complex character can be written to the screen. If the complex character does not include a spacing character, any non-spacing characters are associated with the spacing complex character that exists at the specified screen position. When the application reads information back from the screen, it obtains spacing complex characters.
The cchar_t data type represents a complex character and its rendition. When a cchar_t represents a non-spacing complex character (that is, when there is no spacing character within the complex character), then its rendition is not used. When it is written to the screen, it uses the rendition specified by the spacing character already displayed.
An object of type cchar_t can be initialized using the setchar subroutine, and its contents can be extracted using the getchar subroutine. The behavior of functions that take a cchar_t value that was not initialized in this way are obtained from a curses function that has a cchar_t output argument.
Some functions process special characters. In functions that do not move the cursor based on the information placed in the window, these special characters would only be used within a string in order to affect the placement of subsequent characters. The cursor movement specified below does not persist in the visible cursor beyond the end of the operation. In functions that do not move the cursor, these special characters can be used to affect the placement of subsequent characters and to achieve movement of the physical cursor.
The curses functions that perform special-character processing conceptually convert control characters to the ( ' ^ ' ) character followed by a second character (which is an uppercase letter if it is alphabetic) and write this string to the window in place of the control character. The functions that retrieve text from the window will not retrieve the original control character.
You can use the following variables to add line-drawing characters to the screen with the waddch subroutine. When defined for the terminal, the variable will have the A_ALTCHARSET bit turned on. Otherwise, the default character listed in the following table is stored in the variable.
| Variable Name | Default Character | Glyph Description |
|---|---|---|
| ACS_ULCORNER | + | upper left corner |
| ACS_LLCORNER | + | lower left corner |
| ACS_URCORNER | + | upper right corner |
| ACS_LRCORNER | + | lower right corner |
| ACS_RTEE | + | right tee |
| ACS_LTEE | + | left tee |
| ACS_BTEE | + | bottom tee |
| ACS_TTEE | + | top tee |
| ACS_HLINE | -- | horizontal line |
| ACS_VLINE | | | vertical line |
| ACS_PLUS | + | plus |
| ACS_S1 | - | scan line 1 |
| ACS_S9 | _ | scan line 9 |
| ACS_DIAMOND | + | diamond |
| ACS_CKBOARD | : | checkerboard (stipple) |
| ACS_DEGREE | , | degree symbol |
| ACS_PLMINUS | # | plus/minus |
| ACS_BULLET | o | bullet |
| ACS_LARROW | < | arrow pointing left |
| ACS_RARROW | > | arrow pointing right |
| ACS_DARROW | v | arrow pointing down |
| ACS_UARROW | ^ | arrow pointing up |
| ACS_BOARD | # | board of squares |
| ACS_LANTERN | # | lantern symbol |
| ACS_BLOCK | # | solid square block |
The waddstr subroutines add a null-terminated character string to a window, starting with the current character. If you are adding a single character, use the waddch subroutine. Otherwise, use the waddstr subroutine. The following are part of the waddstr subroutine family:
| addstr macro | Adds a character string to the stdscr |
| mvaddstr macro | Moves the logical cursor to a specified location before adding a character string to the stdscr |
| wmvaddstr macro | Moves the logical cursor to a specified location before adding a character string to a user-defined window |
| waddstr subroutine | Adds a character string to a user-defined window |
The winsch subroutines insert a specified character before the current character in a window. All characters to the right of the inserted character are moved one space to the right. As a result, the rightmost character on the line may be lost. The positions of the logical and physical cursors do not change after the move. The winsch subroutines include the following:
The winsertln subroutines insert a blank line above the current line in a window. The insertln subroutine inserts a line in the stdscr. The bottom line of the window is lost. The winsertln subroutine performs the same action in a user-defined window.
The wprintw subroutines replace a series of characters (starting with the current character) with formatted output. The format is the same as for the printf command. The printw family is made up of the following:
The wprintw subroutines make calls to the waddch subroutine to replace characters.
The unctrl macro returns a printable representation of the specified control character, displayed in the ^X notation. The unctrl macro returns print characters as is.
Use the following subroutines to enable scrolling:
| idlok | Allows curses to use the hardware insert/delete line feature. |
| scrollok | Enables a window to scroll when the cursor is moved off the right edge of the last line of a window. |
| setscrreg or wsetscrreg | Sets a software scrolling region within a window. |
Scrolling occurs when a program or user moves a cursor off a window's bottom edge. For scrolling to occur, you must first use the scrollok subroutine to enable scrolling for a window. A window is scrolled if scrolling is enabled and if any of the following occurs:
When a window is scrolled, curses will update both the window and the display. However, to get the physical scrolling effect on the terminal, you must call the idlok subroutine with the Flag parameter set to TRUE.
If scrolling is disabled, the cursor remains on the bottom line at the location where the character was entered.
When scrolling is enabled for a window, you can use the setscrreg subroutines to create a software scrolling region inside the window. You pass the setscrreg subroutines values for the top line and bottom line of the region. If setscrreg is enabled for the region and scrolling is enabled for the window, any attempt to move off the specified bottom line causes all the lines in the region to scroll up one line. You can use the setscrreg macro to define a scrolling region in the stdscr. Otherwise, you use the wsetscrreg subroutine to define scrolling regions in user-defined windows.
You can delete text by replacing it with blank spaces or by removing characters from a character array and sliding the rest of the characters on the line one space to the left.
The erase macro copies blank space to every position in the stdscr. The werase subroutine puts a blank space at every position in a user-defined window. To delete a single character in a window, use the wdelch subroutine.
Use the following subroutines to clear the screen:
| clear, or wclear | Clears the screen and sets a clear flag for the next refresh. |
| clearok | Determines whether curses clears a window on the next call to the refresh or wrefresh subroutine. |
The wclear subroutines are similar to the werase subroutines. However, in addition to putting a blank space at every position of a window, the wclear subroutines also call the wclearok subroutine. As a result, the screen is cleared on the next call to the wrefresh subroutine.
The wclear subroutine family contains the wclear subroutine, the clear macro, and the clearok subroutine. The clear macro puts a blank at every position in the stdscr.
The clrtoeol macro operates in the stdscr, while the wclrtoeol subroutine performs the same action within a user-defined window.
The clrtobot macro operates in the stdscr, while the wclrtobot performs the same action in a user-defined window.
Use the following subroutines to delete characters from the screen:
The wdelch subroutines delete the current character and move all the characters to the right of the current character on the current line one position to the left. The last character in the line is filled with a blank. The delch subroutine family consists of the following subroutine and macros:
The deleteln subroutines delete the current line and move all lines below the current line up one line. This clears the window's bottom line.
Your program can retrieve characters from the keyboard or from the display. The wgetch subroutines retrieve characters from the keyboard. The winch subroutines retrieve characters from the display.
The wgetch subroutines read characters from the keyboard attached to the terminal associated with the window. Before getting a character, these subroutines call the wrefresh subroutines if anything in the window has changed: for example, if the cursor has moved or text has changed. If the wgetch subroutine encounters a Ctrl-D key sequence during processing, it returns.
The wgetch subroutine family is made up of the following:
To place a character previously obtained by a call to the wgetch subroutine back in the input queue, use the ungetch subroutine. The character is retrieved by the next call to the wgetch subroutine.
The output of the wgetch subroutines is, in part, determined by the mode of the terminal. The following list describes the action of the wgetch subroutines in each type of terminal mode:
Function keys are defined in the curses.h file. Function keys can be returned by the wgetch subroutine if the keypad is enabled. A terminal may not support all of the function keys. To see if a terminal supports a particular key, check its terminfo database definition. The following table lists the function keys defined in the curses.h file:
| Name | Key Name |
| KEY_BREAK | Break key (unreliable) |
| KEY_DOWN | Down arrow key |
| KEY_UP | Up arrow key |
| KEY_LEFT | Left arrow key |
| KEY_RIGHT | Right arrow key |
| KEY_HOME | Home key (upward + left arrow) |
| KEY_BACKSPACE | Backspace (unreliable) |
| KEY F0 | Function keys. Space for 64 keys is reserved |
| KEYF(n) | Formula for fn. |
| KEY_DL | Delete line |
| KEY_IL | Insert line |
| KEY_DC | Delete character |
| KEY_IC | Insert character or enter insert mode |
| KEY_EIC | Exit insert character mode |
| KEY_CLEAR | Clear screen |
| KEY_EOS | Clear to end of screen |
| KEY_EOL | Clear to end of line |
| KEY_SF | Scroll 1 line forward |
| KEY_SR | Scroll 1 line backward (reverse) |
| KEY_NPAGE | Next page |
| KEY_PPAGE | Previous page |
| KEY_STAB | Set tab |
| KEY_CTAB | Clear tab |
| KEY_CATAB | Clear all tabs |
| KEY_ENTER | Enter or send |
| KEY_SRESET | Soft (partial) reset |
| KEY_RESET | Reset or hard reset |
| KEY_PRINT | Print or copy |
| KEY_IL | Home down or bottom (lower left) keypad |
| KEY_A1 | Upper left of keypad |
| KEY_A3 | Upper right of keypad |
| KEY_B2 | Center of keypad |
| KEY_C1 | Lower left of keypad |
| KEY_C3 | Lower right of keypad |
| KEY_BTAB | Back tab key |
| KEY_BEG | Beginning key |
| KEY_CANCEL | Cancel key |
| KEY-CLOSE | Close key |
| KEY_COMMAND | Command key |
| KEY_COPY | Copy key |
| KEY_CREATE | Create key |
| KEY_END | End key |
| KEY_EXIT | Exit key |
| KEY_FIND | Find key |
| KEY_HELP | Help key |
| KEY_MARK | Mark key |
| KEY_MESSAGE | Message key |
| KEY_MOVE | Move key |
| KEY_NEXT | Next object key |
| KEY_OPEN | Open key |
| KEY_OPTIONS | Options key |
| KEY_PREVIOUS | Previous object key |
| KEY_REDO | Redo key |
| KEY_REFERENCE | Reference key |
| KEY_REFRESH | Refresh key |
| KEY_REPLACE | Replace key |
| KEY_RESTART | Restart key |
| KEY_RESUME | Resume key |
| KEY_SAVE | Save key |
| KEY_SBEG | Shifted beginning key |
| KEY_SCANCEL | Shifted cancel key |
| KEY_SCOMMAND | Shifted command key |
| KEY_SCOPY | Shifted copy key |
| KEY_SCREATE | Shifted create key |
| KEY_SDC | Shifted delete-character key |
| KEY_SDL | Shifted delete-line key |
| KEY_SELECT | Select key |
| KEY_SEND | Shifted end key |
| KEY_SEOL | Shifted clear-line key |
| KEY_SEXIT | Shifted exit key |
| KEY_SFIND | Shifted find key |
| KEY_SHELP | Shifted help key. |
| KEY_SHOME | Shifted home key |
| KEY_SIC | Shifted input key |
| KEY_SLEFT | Shifted left arrow key |
| KEY_SMESSAGE | Shifted message key |
| KEY_SMOVE | Shifted move key |
| KEY_SNEXT | Shifted next key |
| KEY_SOPTIONS | Shifted options key |
| KEY_SPREVIOUS | Shifted previous key |
| KEY_SPRINT | Shifted print key |
| KEY_SREDO | Shifted redo key |
| KEY_SREPLACE | Shifted replace key |
| KEY_SRIGHT | Shifted right arrow key |
| KEY_SRSUME | Shifted resume key |
| KEY_SSAVE | Shifted save key |
| KEY_SSUSPEND | Shifted suspend key |
| KEY_SUNDO | Shifted undo key |
| KEY_SUSPEND | Suspend key |
| KEY_UNDO | Undo key |
If your program enables the keyboard with the keypad subroutine, and the user presses a function key, the token for that function key is returned instead of raw characters. The /usr/include/curses.h file defines the possible function keys. Each define statement begins with a KEY_ prefix, and the keys are defined as integers beginning with the value 03510.
If a character is received that could be the beginning of a function key (such as an Escape character), curses sets a timer (a structure of type timeval that is defined in /usr/include/sys/time.h). If the remainder of the sequence is not received before the timer expires, the character is passed through. Otherwise, the function key's value is returned. For this reason, after a user presses the Esc key there is a delay before the escape is returned to the program. Avoid using the Esc key where possible when you call a single-character subroutine such as the wgetch subroutine. This timer can be overridden or extended by the use of the ESCDELAY environment variable.
The ESCDELAY environment variable sets the length of time to wait before timing out and treating the ESC keystroke as the Escape character rather than combining it with other characters in the buffer to create a key sequence. The ESCDELAY value is measured in fifths of a millisecond. If the ESCDELAY variable is 0, the system immediately composes the Escape response without waiting for more information from the buffer. You may choose any value from 0 to 99,999. The default setting for the ESCDELAY variable is 500 (1/10th of a second).
To prevent the wgetch subroutine from setting a timer, call the notimeout subroutine. If notimeout is set to TRUE, curses does not distinguish between function keys and characters when retrieving data.
The keyname subroutine returns a pointer to a character string containing a symbolic name for the Key argument. The Key argument can be any key returned from the wgetch, getch, mvgetch, or mvwgetch subroutines.
The winch subroutines retrieve the character at the current position. If any attributes are set for the position, the attribute values are ORed into the value returned. You can use the winch subroutines to extract only the character or its attributes. To do this, use the predefined constants A_CHARTEXT and A_ATTRIBUTES with the logical & (ampersand) operator. These constants are defined in the curses.h file. The following are the winch subroutines:
The wscanw subroutines read character data, interpret it according to a conversion specification, and store the converted results into memory. The wscanw subroutines use the wgetstr subroutines to read the character data. The following are the wscanw subroutines:
The vwscanw subroutine scans a window using a variable argument list. For information about manipulating variable argument lists, see the varargs macros in AIX 5L Version 5.2 Technical Reference: Base Operating System and Extensions Volume 2.