5.2.8 Character and window attribute control routines

These routines manipulate the current attributes of the named window. The current attributes of a window apply to all characters that are written into the window with addch and addstr. Attributes are a property of the character, and move with the character through any scrolling and insert/delete line/character operations. To the extent possible, they are displayed as appropriate modifications to the graphic rendition of characters put on the screen.

Procedure: attr-set! win attrs #:optional color

Procedure: attr-on! win attrs

Procedure: attr-off! win attrs

Procedure: standend! win

Procedure: standout! win

The routine attr-set! sets the current rendition (attributes and color pair) of the given window to attrs. Optionally, you may split the color-pair information as a third parameter.

attrs is one of the attribute constants: there is an attribute constant for each of the attributes mentioned in Making rendered characters: A_BLINK, A_BOLD, A_DIM, A_INVIS, A_NORMAL, A_PROTECT, A_REVERSE, A_STANDOUT, A_UNDERLINE, A_HORIZONTAL, A_LEFT, A_LOW, A_RIGHT, A_TOP, A_VERTICAL.

The following two calls are equivalent:

(attr-set! win (logior A_BOLD (color-pair 1)))

or

(attr-set! win A_BOLD 1)

The routine attr-off! turns off the named attributes without turning any other attributes on or off. The routine attr-on! turns on the named attributes without affecting any others. The routine standout! is the same as (attr-on! A_STANDOUT). The routine standend! is the same as (attr-set! A_NORMAL) or (attr-set! 0), that is, it turns off all attributes.

The return value of these routines are undefined. They can throw an exception if curses is in a bad state.

The attr-set! and related routines do not affect the attributes used when erasing portions of the window. For functions which modify the attributes used for erasing and clearing See Window background manipulation routines.

Procedure: color-set! win color-pair-number

The routine color-set! sets the current color of the given window to the foreground/background combination described by the color-pair-number.

The return value is unspecified, but, it can throw an error if the color pair number was too large.

Procedure: attr-get

The routine attr-get returns the current attribute and color pair for the given window. They are returned as a list containing two elements. The first element is a bitmap containing all the attributes. The second element is the color pair alone.

Procedure: chgat win n attr color #:key y x

The routine chgat changes the attributes of a given number of characters starting at the current cursor location of stdscr or of win if it is given. It does not update the cursor and does not perform wrapping. A character count of -1 or greater than the remaining window width means to change attributes all the way to the end of the current line. If y and x are given, the function does a cursor move before acting. In these functions, the color argument is a color-pair index as in the first argument of init-pair!. See Color manipulation routines.

The return value is unspecified.

The attributes can be passed to the routines attr-on!, attr-off!, and attr-set!, or logior’d with the characters passed to addch. For the color part of the rendition, use color-pair. See Table 5.2.

Procedure: color-pair n

Returns a bit mask to apply the color pair n to a rendition. color-pair values can only be logior’ed with attributes if the pair number is less than 256. The alternate functions such as color-set! can pass a color pair value directly.

For example, the following two calls are equivalent ways of setting the default attribute of the screen to be bold and have color-pair #1.

(attr-set! win (logior A_BOLD (color-pair 1)))

or

(attr-set! win A_BOLD 1)

Procedure: pair-number attrs

This function is the inverse operation of color-pair. It is rarely useful.

(color-pair 1) ==> 256
(pair-number 256) ==> 1