Manipulating Characters with Curses

You can add characters to a curses window by way of a keyboard or a curses application. This section provides an overview of the ways you can add, remove, or change characters that appear in a curses window.
The following topics are covered:

• Adding Characters to the Screen Image
• Enabling Text Scrolling
• Deleting Characters
• Getting Characters

Character Size

Historically, a position on the screen has corresponded to a single stored byte. This correspondence is no longer true for several reasons:

• Some characters may occupy several columns when displayed on the screen.
• Some characters may be non-spacing characters, defined only in association with a spacing character.
• The number of bytes to hold a character from the extended character sets depends on the LC_CTYPE locale category.

Some character sets define multi-column characters that occupy mare 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.

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. The following subroutine families add text to windows:

• waddch
• waddstr
• winsch
• winsertln
• wprintw

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

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

Note: Calling the winch subroutine on a position in the window containing a control character does not return the character. Instead, it returns one character of the control character representation.

Outputting Single, Noncontrol Characters

When outputting single, noncontrol characters, there is 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. (Non-spacing characters are those, other than the ' \ 0 ' character, for which wcwidth ( ) returns a width of zero.) The application may write non-spacing characters to a window. Every non-spacing character in a window is associated with a spacing character and modifies the spacing character. Non-spacing characters in a window cannot be addressed separately. A non-spacing character is implicitly addressed whenever a Curses operation affects the spacing character with which the non-spacing 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 non-spacing character. Multi-column characters have a single set of attributes for all columns. The association of non-spacing characters with spacing characters can be controlled by the application using the wide character interfaces. The wide character string functions provide codeset-dependent association.

Two typical effects of a non-spacing character associated with a spacing character called c, are as follows:

• The non-spacing character may modify the appearance of c. (For instance, there may be non-spacing characters that add diacritical marks to characters. However, there may also be spacing characters with built-in diacritical marks.)
• The non-spacing 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 non-spacing 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 include any non-spacing characters associated with it. A spacing complex character is a spacing character followed by any non-spacing characters associated with it. That is, a spacing complex character is a complex character that includes one spacing character. 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 it 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 setchar( ) and its contents can be extracted using getchar( ). The behavior of functions that take a cchar_t value that was not initialized in this way or obtained from a curses function that has a cchar_t output argument.

Special Characters

Some functions process special characters as specified below.

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 visible 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 upper-case letter if it is alphabetic) and write this string to the window in place of the control character. The funtions 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 will be stored in the variable.

waddstr Subroutines

The waddstr subroutines add a null-terminated character string to a window, starting with the current character. Calling an waddstr subroutine is equivalent to calling the corresponding waddch subroutine once for each character in the string. 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:

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 wprintw performs the same action as the printw subroutine but in a user-defined window. The following subroutine and macros belong to the printw family:

The wprintw subroutines make calls to the waddch subroutine to replace characters.

unctrl Macro

The unctrl macro returns a printable representation of the specified character. Control characters are 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 occur:

• The cursor is moved off the edge of a window.
• A new-line character is encountered on the last line.
• After 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 is left 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.

Note: Unlike the idlok subroutine, the setscrreg subroutines have nothing to do with the use of the physical scrolling region capability that the terminal may or may not have.

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. Use the following subroutine families to delete text:

• werase
• wclear
• wclrto
• wdelch
• wdeleteln

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 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 wclear subroutine puts a blank space at every position in the user-defined window. The clearok subroutine causes the next call to the refresh subroutine to clear and redraw the entire window.

wclrtoeol Subroutines

The clrtoeol macro erases from the right of the cursor to the end of the current line in the stdscr. The wclrtoeol subroutine performs the same action within a user-defined window.

wclrtobot Subroutines

The clrtobot macro erases from the right of the cursor to the end of the stdscr. 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 wdeleteln subroutines delete the current line and move all lines below the current line up one line. This clears the window's bottom line. The deleteln macro deletes lines within the stdscr. The wdeleteln subroutine deletes lines in a user-defined window.

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. If the wgetch subroutine encounters a Ctrl-D key sequence during processing, it returns.

The following belong to the wgetch subroutine family:

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 Importance of 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:

Note: When you use the wgetch subroutines do not set both the NOCBREAK mode and the ECHO mode at the same time. Setting both modes can cause undesirable results depending on the state of the tty driver when each character is typed.

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. The following table lists the function keys defined in the curses.h file:

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 possible function keys are defined in the /usr/include/curses.h file. 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 escape key there is a delay before the escape is returned to the program. You should avoid using the escape 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 environment variable ESCDELAY.

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

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

Related Information

Curses Overview for Programming

Understanding Terminals with Curses