4    Handling Wide-Character Data with curses Library Routines

The curses Library provides functions for developing user interfaces on character-cell terminals. This chapter discusses enhancements made to the curses Library to support wide-character format, which accommodates multibyte characters.

The recommended functions for handling multibyte characters in wide-character or complex-character format conform to Version 4.2 of the X/Open Curses CAE specification and supersede those specified by the System V Multi-National Language Supplement (MNLS).

This chapter summarizes the curses Library functions and macros that process characters and character strings from the screen or keyboard. Tables in each section note if more than one curses interface is available to perform the same operation and recommend the curses interface that is best suited for writing international software. That is, the tables highlight the curses Library functions and macros that handle wide-character or complex-character format and conform to the X/Open Curses CAE specification. Make sure your application uses the curses interface listed in the Recommended Routine column of the table.

The Section 3 reference pages provide syntax and detailed information for each interface. Use this chapter to determine the interface needed for the operation you want to perform; then use the man command to display the reference page for the chosen interface. For an overview of all the functions in the curses Library, see curses(3).

Note

Some curses routines overwrite existing characters on the curses window. Only the routines that use the wchar_t or cchar_t data type ensure that overwriting does not leave partial characters on the screen. When the display width of an overwritten character is greater than one column, as may be the case for multibyte characters, these routines write extra blank characters to remove partial characters. For example, if the English language character a overwrites the first column of a 2-column Chinese language character, the second column of the Chinese character is overwritten with a blank.

Behavior is undefined when you overwrite multibyte characters with curses routines that have not been internationalized.

4.1    Writing a Wide Character to a curses Window

The following sections discuss routines that add or insert individual wide characters on a curses window. These routines perform one of the following operations if a character already exists at the target position:

• Overwrite the existing character and then advance the cursor

• Insert the new character before the existing one and do not advance the cursor

4.1.1    Add Wide Character (Overwrite) and Advance Cursor

The routines listed in Table 4-1 add a wide character and its attributes to a window on the screen and advance the cursor. If a character already exists at the target position, the character is overwritten by the one being added.

Your choice of routine depends on whether you need to do the following:

• Add the character to the default or a specified window

• Add the character at the current or specified coordinates

• Refresh the screen

Use the const cchar_t data type to pass a wide character with its attributes to these routines.

Table 4-1:  curses Routines to Add Wide Characters and Advance the Cursor

4.1.2    Insert Wide Character (No Overwrite) and Do Not Advance Cursor

The routines listed in Table 4-2 insert a wide character in a window at the current or specified coordinates and do not change the position of the cursor after the write operation. The wide character is inserted before an existing character at the target position, so these routines do not overwrite characters that already exist on the line. Existing characters at and to the right of the target position are moved further to the right and the character in the rightmost position is truncated. Your choice of interface in this category depends on whether you want to do the following:

• Write to the default or a specified window

• Write at the current or specified coordinates

Table 4-2:  curses Routines to Insert Wide Characters and Not Advance the Cursor

4.2    Writing a Wide-Character String to a curses Window

The following sections discuss routines that add or insert wide-character strings in curses windows.

4.2.1    Add Wide-Character String (Overwrite) and Do Not Advance Cursor

The routines listed in Table 4-3 add a wide-character string and its character attributes to a window. However, these routines also behave as follows:

• Do not advance the position of the cursor

• Do not check the string for special characters (such as newline, tab, and backspace) that usually affect cursor position

• Truncate the string rather than wrapping it to the next line

Characters in the string that these routines add overwrite characters that already exist at the target position. Your choice of interface in this category depends on whether you need to do the following:

• Write all or some of the characters in the string

• Write the characters to the default or a specified window

• Write the characters at the current or specified coordinates

Table 4-3:  curses Routines to Add Wide-Character Strings and Not Advance the Cursor

4.2.2    Add Wide-Character String (Overwrite) and Advance Cursor

As with the routines discussed in Section 4.2.1, the routines listed in Table 4-4 also add a wide-character string (but without video-character attributes) to a window and overwrite existing characters. However, these routines also do the following:

• Advance the position of the cursor

• Check the string for special characters (such as newline, tab, and backspace) that can also affect the position of characters

• Wrap strings to the next line rather than truncating them

Your choice of interface in this category depends on whether you want to do the following:

• Write all or a specified number of characters in the string

• Write the characters to the default or a specified window

• Write the characters at the current or specified coordinates

Table 4-4:  curses Routines to Add Wide-Character Strings and Advance the Cursor

4.2.3    Insert Wide-Character String (no Overwrite) and Do Not Advance Cursor

The routines listed in Table 4-5 insert a wide-character string before a target position in a curses window. These routines do the following:

• Move further to the right any existing characters that are at and to the right of the target position

  Existing characters are not overwritten, but rightmost characters may be truncated at the end of the line

• Check the string for special characters (such as newline, tab, and backspace) that can affect character and cursor placement

• Do not advance the cursor after the write operation

Your choice of interface in this category depends on whether you need to do the following:

• Write all or some of the characters in the string

• Write the characters to the default or a specified window

• Write the characters at the current or specified coordinates

Table 4-5:  curses Routines to Insert Wide-Character Strings and Not Advance the Cursor

4.3    Removing a Wide Character from a curses Window

The routines listed in Table 4-6 delete a wide character at the target position in a curses window. Characters that follow the deleted character on the line shift one character to the left. These routines existed in the curses Library before multibyte characters were supported and have been redefined for correct handling of wide-character format.

Your choice of interface in this category depends on whether you need to do the following:

• Delete a wide character in the default or a specified window

• Delete a wide character at the current or specified coordinates

Table 4-6:  curses Routines to Remove a Wide Character

4.4    Reading a Wide Character from a curses Window

The routines listed in Table 4-7 read a wide character and its video attributes from a curses window. The data returned to the program is of data type cchar_t, so that both the wide character and its attributes are stored.

Your choice of interface in this category depends on whether the character being read is one of the following:

• In the default or a specified window

• At the current or specified coordinates

Table 4-7:  curses Routines to Read Wide Characters From a Window

4.5    Reading a Wide-Character String from a curses Window

Two sets of routines allow you to read a wide-character string from a curses window. The set of routines described in Section 4.5.1 retrieve strings that include wide characters with their video attributes. The set of routines described in Section 4.5.2 strip attributes from the characters in the string.

4.5.1    Reading Wide-Character Strings with Attributes

The routines listed in Table 4-8 read a wide-character string and its character attributes from a curses window. The string returned by the recommended routines is of the data type cchar_t.

Your choice of interface in this category depends on whether you want to do the following:

• Read all or up to a specified number of wide characters in the string

• Read characters from the default or a specified window

• Read characters that are at the current or specified coordinates

Table 4-8:  curses Routines to Read Wide-Character Strings With Attributes

4.5.2    Reading Wide-Character Strings Without Attributes

The routines listed in Table 4-9 read a wide-character string from a curses window and store a string of data type wchar_t in a program variable. Video attributes are stripped from the characters included in the string.

Your choice of interface in this category depends on whether you want to do the following:

• Read all or up to a specified number of characters in the string

• Read characters from the default or a specified window

• Read characters that are at the current or specified coordinates of the window

Table 4-9:  curses Routines to Read Wide-Character Strings Without Attributes

4.6    Reading a String of Characters from a Terminal

The routines listed in Table 4-10 get strings of characters from the terminal associated with a curses window and store the characters in a program buffer.

Your choice of interface in this category depends on whether you want to do the following:

• Read all or up to a specified number of characters in a string

• Read characters for use in the default or a specified window

• Read characters for use at the current or specified coordinates on the window

Table 4-10:  curses Routines to Read Wide-Character Strings From a Terminal

4.7    Reading or Queuing a Wide Character from the Keyboard

The routines listed in Table 4-11 get a single-byte or multibyte character from the terminal keyboard associated with a curses window, convert the character to wide-character format, and return the character to the program. Unless curses input mode is set to noecho, these routines also echo each character back to the screen.

The unget_wch interface places the wide character at the head of the input queue. In this case, the next call to wget_wch returns the character from the input queue to the program.

Your choice of interface in this category depends on the following uses of the character:

• Use with the default or a specified window

• Use at the current or specified position of the window

• Immediate or delayed use

Table 4-11:  curses Routines for Reading Wide Characters From the Keyboard

4.8    Converting Formatted Text in a curses Window

The routines listed in Table 4-12 read wide characters from a curses window and convert them. These functions existed in the curses Library before it was internationalized and have been enhanced to handle wide-character data. In all cases, these functions call wgetstr to read a wide-character string from a window and then interpret and convert characters according to scanf() function rules. See scanf(3) for more information.

Your choice of interface in this category depends on whether you do the following:

• Convert a string in the default or a specified window

• Convert a string starting at the current or specified coordinates

• Need to include a list of variables as one of the arguments in the call

Table 4-12:  curses Routines to Convert Formatted Text in a Window

4.9    Printing Formatted Text on a curses Window

The routines listed in Table 4-13 format a string and then print it on a curses window. The functions existed in the curses Library before it was internationalized and have been redefined to process data in wide-character format. These functions are analogous to printf() (or vprintf()) formatting the string and then addstr() (or waddstr()) writing it. See printf(3) for formatting information.

Your choice of interface in this category depends on whether you need to do the following:

• Print on the default or a specified window

• Print at the current or a specified position

• Include a list of variables as one of the call arguments

Table 4-13:  curses Routines to Print Formatted Text on a Window