Manipulating characters with curses

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.

Character size

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 produces an error.

Adding characters to the screen image

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.

waddch subroutines

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 the scrollok subroutine 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.

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.

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

Outputting single, noncontrol characters

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 nonspacing 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.

Nonspacing 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:

• The nonspacing character may modify the appearance of c. (For instance, there may be nonspacing characters that add diacritical marks to characters. However, there may also be spacing characters with built-in diacritical marks.)
• The nonspacing characters may bridge c to the character following c. Examples of this usage are the formation of ligatures and the conversion of characters into compound display forms, words, or ideograms.

Implementations may limit the number of nonspacing characters that can be associated with a spacing character, provided any limit is at least 5.

Complex characters

A complex character is a set of associated characters, which may include a spacing character and may also include any nonspacing characters associated with it. A spacing complex character is a complex character that includes one spacing character and any nonspacing 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 nonspacing 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 nonspacing 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.

Special characters

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.

Control characters

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.

Line graphics:

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.

waddstr subroutines

winsch subroutines

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:

winsertln subroutines

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.

wprintw subroutines

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.

unctrl macro

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.

Enabling text scrolling

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:

• The cursor is moved off the edge of a window.
• A newline character is encountered on the last line.
• A character is inserted in the last position of the last line.

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.

Deleting characters

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.

werase subroutines

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.

wclear subroutines

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 clearok 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.

wclrtoeol subroutines

The clrtoeol macro operates in the stdscr, while the wclrtoeol subroutine performs the same action within a user-defined window.

wclrtobot subroutines

The clrtobot macro operates in the stdscr, while the wclrtobot performs the same action in a user-defined window.

wdelch subroutines

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:

wdeleteln subroutines

The deleteln subroutines delete the current line and move all lines below the current line up one line. This action clears the window's bottom line.

Getting characters

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.

wgetch subroutines

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. For more information, see wgetch Subroutine, in Technical Reference: Base Operating System and Extensions, Volume 2.

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.

Terminal modes

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

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. For a list of function keys, see getch, mvgetch, mvwgetch, or wgetch Subroutine, in Technical Reference: Base Operating System and Extensions, Volume 2.

Getting function keys

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.

keyname subroutine

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.

winch 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:

wscanw 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 Technical Reference: Base Operating System and Extensions, Volume 2.