5.2.5 Making rendered characters

Many curses functions take rendered, complex characters: characters with associated color and attribute information.

For those who are familiar with the C API for ncurses, you know that a rendered character is either a chtype, which is a 32-bit integer containing an 8-bit char and 24-bits of color and rendering information, or is a cchar_t, which is one or more wchar_t characters plus associated color and rendering information. Guile-Ncurses abstracts away the difference between these two types and presents a consistent API for both. The Guile-Ncurses complex rendered character will get converted automatically to chtype or cchar_t when necessary.

There is a family of functions to convert unrendered, simple characters or strings to rendered complex characters and strings.

Procedure: blink x

Procedure: bold x

Procedure: dim x

Procedure: horizontal x

Procedure: invis x

Procedure: left x

Procedure: low x

Procedure: normal x

Procedure: protect x

Procedure: inverse x

Procedure: right x

Procedure: standout x

Procedure: top x

Procedure: underline x

Procedure: vertical x

These procedures take x, which can be either a simple character, a complex character, a simple string, or a complex string, and returns a rendered character or string with the attribute blink, bold, dim, horizontal, invisible, left, low, normal, protect, inverse, right, top, underline, or vertical, respectively. If the input x was a rendered character or a rendered string, the old attributes are replaced. If x was a rendered character or string with an associated color pair, the returned character or string will have the same associated color pair.

Note that whether these attributes can actually be visualized depends on the capabilities of the terminal itself. Most terminals can handle bold, dim, inverse, and sometimes blink, underline and invisible. The rest should probably not be used.

Procedure: blink-on x

Procedure: bold-on x

Procedure: dim-on x

Procedure: horizontal-on x

Procedure: invis-on x

Procedure: left-on x

Procedure: low-on x

Procedure: normal-on x

Procedure: protect-on x

Procedure: inverse-on x

Procedure: right-on x

Procedure: standout-on x

Procedure: top-on x

Procedure: underline-on x

Procedure: vertical-on x

These procedures take x, which can be either a simple character, a complex character, a simple string, or a complex string. If x is a simple character or simple string, it sets its rendering to blink, bold, dim, horizontal, invisible, left, low, normal, protect, inverse, right, top, underline, or vertical, respectively. If the input x was a rendered character or a rendered string, these attributes are added to the rendered character.

Most terminals can’t actually visualize multiple attributes on a single character: some terminals can handle the combination of blink and bold, bold and underline, or inverse and bold.

Procedure: blink-off x

Procedure: bold-off x

Procedure: dim-off x

Procedure: horizontal-off x

Procedure: invis-off x

Procedure: left-off x

Procedure: low-off x

Procedure: normal-off x

Procedure: protect-off x

Procedure: inverse-off x

Procedure: right-off x

Procedure: standout-off x

Procedure: top-off x

Procedure: underline-off

Procedure: vertical-off x

These procedures take x, which can be either a simple character, a complex character, a simple string, or a complex string. If x is a simple character or simple string, it sets its rendering to normal. If the input x was a rendered character or a rendered string and had the given attribute, these attributes is removed from the resulting rendered character.

Procedure: color n x

These procedure takes x, which can be either a simple character, a complex character, a simple string, or a complex string. It returns a rendered character or string with an associated color pair n.

This procedure should only be used if start-color has been called.

There are a set of primitives to operate directly on complex characters.

Procedure: xchar? c

Returns #t if c is a complex character.

Procedure: xchar-attr c

Procedure: xchar-color c

Procedure: xchar-chars c

These three procedures return the attributes, color pair number, and list of constituent characters of a complex character, respectively.

Procedure: set-xchar-attr! c attr

Procedure: set-xchar-color! c color-pair-number

Procedure: set-xchar-chars! c list-of-chars

These procedures directly set the attributes, color-pair number, and the list of characters of a complex character, respectively.

Complex characters can have a base character and a set of accent characters that overwrite the base character. That is why set-xchar-chars! takes a list of characters, instead of a single character. But, for these complex characters to be rendered correctly on the terminal, you need both a terminal that can do overstrike characters and you need to have compiled with the wide Ncurses library. If either of these conditions are not true, only the first character in the list of characters will appear on the screen.

There are also a couple of low-level functions to do conversion between C characters and Guile characters.

Procedure: %scheme-char-from-c-char c

Given an 8-bit integer c that represents a C character in the current locale, this returns the associated scheme character.

Procedure: %scheme-char-to-c-char c

This returns an 8-bit integer that is the C representation of character c in the current locale. If the character cannot be represented in the current locale, it will return the integer 63, which is the ASCII code for the question mark.

Procedure: %scheme-char-from-c-wchar c

Given an integer c that represents a wchar_t representation of a C wide character, this returns the associated scheme character.

Procedure: %scheme-char-to-c-wchar c

This returns an integer that is the C wchar_t representation of character c. If the character cannot be represented in the current locale, it will return the integer #xFFFD, which is the Unicode codepoint for the replacement character.