4    Handling Wide-Character Data with curses 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 supercede those specified by the System V Multi-National Language Supplement (MNLS).

This chapter summarizes the curses functions and macros that process characters and character strings from the screen or keyboard. Tables in each section note if there is more than one curses interface available to perform the same operation, but only one handles wide-character or complex-character format and conforms to the X/Open Curses CAE specification. In such cases, 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 character a overwrites the first column of a 2-column Chinese 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 different categories of 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 functions and macros in the following table add a wide character, along with 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:

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

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

The following functions and macros 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:

• Write to the default or a specified window

• Write at the current or specified coordinates

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 functions and macros in the following table add a wide-character string, along with character attributes, to a window. These routines:

• 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 around 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:

• 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

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

Like the functions and macros discussed in the preceding section, the routines in the following table also add a wide-character string (but without video-character attributes) to a window and overwrite existing characters. However, these routines also:

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

• 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

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

The functions and macros discussed in this section insert a wide-character string before a target position in a curses window. These routines:

• Move further to the right any existing characters 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:

• 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

4.3    Removing a Wide Character from a curses Window

The function and macros in the following table 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:

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

• Delete a wide character at the current or specified coordinates

4.4    Reading a Wide Character from a curses Window

The function and macros in this section read a wide character, along with 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:

• In the default or a specified window

• At the current or specified coordinates

4.5    Reading a Wide-Character String from a curses Window

There are two sets of routines that allow you to read a wide-character string from a curses window. Routines in one set retrieve strings that include wide characters with their video attributes. Routines in the other set strip attributes from the characters in the string.

4.5.1    Reading Wide-Character Strings with Attributes

The function and macros in the following table read a wide-character string, along with 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:

• 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

4.5.2    Reading Wide-Character Strings Without Attributes

The function and macros in the following table 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:

• 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

4.6    Reading a String of Characters from a Terminal

The function and macros in the following table 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:

• 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

4.7    Reading or Queuing a Wide Character from the Keyboard

Most functions or macros in the following table 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 whether you get the character for:

• Use with the default or a specified window

• Use at the current or specified position of the window

• Immediate or delayed use

4.8    Converting Formatted Text in a curses Window

The following functions 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. Refer to scanf(3) for more information.

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

• 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

4.9    Printing Formatted Text on a curses Window

The functions in the following table 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. Refer to printf(3) for formatting information.

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

• 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