# curs_attr

## NAME



           **attr_get** , **wattr_get** , **attr_set** , **wattr_set** , **attr_off** , **wattr_off** ,
           **attr_on** , **wattr_on** , **attroff** , **wattroff** , **attron** , **wattron** , **attrset** ,
           **wattrset** , **chgat** , **wchgat** , **mvchgat** , **mvwchgat** , **color_set** , **wcolor_set** ,
           **standend** , **wstandend** , **standout** , **wstandout** - **curses** character and
           window attribute control routines
    


## SYNOPSIS



           **#include <curses.h>**
    
           **int attr_get(attr_t ***_attrs_**, short ***_pair_**, void ***_opts_**);**
           **int  wattr_get(WINDOW  ***_win_**,  attr_t  ***_attrs_**,  short  ***_pair_**,  void**
           *****_opts_**);**
           **int attr_set(attr_t** _attrs_**, short** _pair_**, void ***_opts_**);**
           **int wattr_set(WINDOW ***_win_**, attr_t** _attrs_**, short** _pair_**, void ***_opts_**);**
    
           **int attr_off(attr_t** _attrs_**, void ***_opts_**);**
           **int wattr_off(WINDOW ***_win_**, attr_t** _attrs_**, void ***_opts_**);**
           **int attr_on(attr_t** _attrs_**, void ***_opts_**);**
           **int wattr_on(WINDOW ***_win_**, attr_t** _attrs_**, void ***_opts_**);**
    
           **int attroff(int** _attrs);_
           **int wattroff(WINDOW ***_win_**, int** _attrs_**);**
           **int attron(int** _attrs_**);**
           **int wattron(WINDOW ***_win_**, int** _attrs_**);**
           **int attrset(int** _attrs_**);**
           **int wattrset(WINDOW ***_win_**, int** _attrs_**);**
    
           **int chgat(int** _n_**, attr_t** _attr_**, short** _pair_**, const void ***_opts_**);**
           **int wchgat(WINDOW ***_win_**,**
                 **int** _n_**, attr_t** _attr_**, short** _pair_**, const void ***_opts_**);**
           **int mvchgat(int** _y_**, int** _x_**,**
                 **int** _n_**, attr_t** _attr_**, short** _pair_**, const void ***_opts_**);**
           **int mvwchgat(WINDOW ***_win, int y, int x_**,**
                 **int** _n,_ **attr_t** _attr_**, short** _pair_**, const void ***_opts_**);**
    
           **int color_set(short** _pair_**, void***_opts_**);**
           **int wcolor_set(WINDOW ***_win_**, short** _pair_**, void***_opts);_
    
           **int standend(void);**
           **int wstandend(WINDOW ***_win_**);**
           **int standout(void);**
           **int wstandout(WINDOW ***_win_**);**
    


## DESCRIPTION



           These routines manipulate the current attributes of the named win‐
           dow, which then apply to all characters that are written into  the
           window with **waddch** , **waddstr** and **wprintw**.  Attributes are a proper‐
           ty  of  the  character,  and  move  with the character through any
           scrolling and insert/delete line/character operations.  To the ex‐
           tent possible, they are displayed as appropriate modifications  to
           the graphic rendition of characters put on the screen.
    
           These routines do not affect the attributes used when erasing por‐
           tions of the window.  See **curs_bkgd**(3X) for functions which modify
           the attributes used for erasing and clearing.
    
           Routines  which  do  not have a **WINDOW*** parameter apply to **stdscr**.
           For example, **attr_set** is the **stdscr** variant of **wattr_set**.
    
       **Window attributes**
           There are two sets of functions:
    
           •   functions for manipulating the window attributes and color:
               **wattr_set** and **wattr_get**.
    
           •   functions for manipulating only the window attributes (not
               color): **wattr_on** and **wattr_off**.
    
           The **wattr_set** function sets the current attributes of the given
           window to _attrs_ , with color specified by _pair_.
    
           Use **wattr_get** to retrieve attributes for the given window.
    
           Use **attr_on** and **wattr_on** to turn on window attributes, i.e., val‐
           ues OR'd together in _attr_ , without affecting other attributes.
           Use **attr_off** and **wattr_off** to turn off window attributes, again
           values OR'd together in _attr_ , without affecting other attributes.
    
       **Legacy window attributes**
           The X/Open window attribute routines which _set_ or _get_ , turn _on_ or
           _off_ are extensions of older routines which assume that color pairs
           are OR'd into the attribute parameter.  These newer routines use
           similar names, because X/Open simply added an underscore (**_**) for
           the newer names.
    
           The **int** datatype used in the legacy routines is treated as if it
           is the same size as **chtype**(used by **addch**(3X)).  It holds the com‐
           mon video attributes (such as bold, reverse), as well as a few
           bits for color.  Those bits correspond to the **A_COLOR** symbol.  The
           **COLOR_PAIR** macro provides a value which can be OR'd into the at‐
           tribute parameter.  For example, as long as that value fits into
           the **A_COLOR** mask, then these calls produce similar results:
    
               attrset(A_BOLD | COLOR_PAIR(_pair_));
               attr_set(A_BOLD, _pair_ , NULL);
    
           However, if the value does not fit, then the **COLOR_PAIR** macro uses
           only the bits that fit.  For example, because in ncurses **A_COLOR**
           has eight (8) bits, then **COLOR_PAIR(**_259_**)** is 4 (i.e., 259 is 4 more
           than the limit 255).
    
           The **PAIR_NUMBER** macro extracts a pair number from an **int**(or
           **chtype**).  For example, the _input_ and _output_ values in these state‐
           ments would be the same:
    
               int value = A_BOLD | COLOR_PAIR(_input_);
               int _output_ = PAIR_NUMBER(value);
    
           The **attrset** routine is a legacy feature predating SVr4 curses but
           kept in X/Open Curses for the same reason that SVr4 curses kept
           it: compatibility.
    
           The remaining **attr** * functions operate exactly like the correspond‐
           ing **attr_** * functions, except that they take arguments of type **int**
           rather than **attr_t**.
    
           There is no corresponding **attrget** function as such in X/Open Curs‐
           es, although ncurses provides **getattrs**(see curs_legacy(3X)).
    
       **Change character rendition**
           The routine **chgat** changes the attributes of a given number of
           characters starting at the current cursor location of **stdscr**.  It
           does not update the cursor and does not perform wrapping.  A char‐
           acter count of -1 or greater than the remaining window width means
           to change attributes all the way to the end of the current line.
           The **wchgat** function generalizes this to any window; the **mvwchgat**
           function does a cursor move before acting.
    
           In these functions, the color _pair_ argument is a color-pair index
           (as in the first argument of **init_pair** , see **curs_color**(3X)).
    
       **Change window color**
           The routine **color_set** sets the current color of the given window
           to the foreground/background combination described by the color
           _pair_ parameter.
    
       **Standout**
           The routine **standout** is the same as **attron(A_STANDOUT)**.  The rou‐
           tine **standend** is the same as **attrset(A_NORMAL)** or **attrset**(0), that
           is, it turns off all attributes.
    
           X/Open does not mark these “restricted”, because
    
           •   they have well established legacy use, and
    
           •   there is no ambiguity about the way the attributes might be
               combined with a color pair.
    


## VIDEO ATTRIBUTES



           The following video attributes, defined in **< curses.h>**, can be
           passed to the routines **attron** , **attroff** , and **attrset** , or OR'd with
           the characters passed to **addch**(see **curs_addch**(3X)).
    
                  **Name           Description**
                  ─────────────────────────────────────────────────────────────────
                  **A_NORMAL** Normal display (no highlight)
                  **A_STANDOUT** Best highlighting mode of the terminal.
                  **A_UNDERLINE** Underlining
                  **A_REVERSE** Reverse video
                  **A_BLINK** Blinking
                  **A_DIM** Half bright
                  **A_BOLD** Extra bright or bold
                  **A_PROTECT** Protected mode
                  **A_INVIS** Invisible or blank mode
                  **A_ALTCHARSET** Alternate character set
                  **A_ITALIC** Italics (non-X/Open extension)
                  **A_CHARTEXT** Bit-mask to extract a character
                  **A_COLOR** Bit-mask to extract a color (legacy routines)
    
           These video attributes are supported by **attr_on** and related func‐
           tions (which also support the attributes recognized by **attron** ,
           etc.):
                  **Name            Description**
                  ─────────────────────────────────────────
                  **WA_HORIZONTAL** Horizontal highlight
                  **WA_LEFT** Left highlight
                  **WA_LOW** Low highlight
                  **WA_RIGHT** Right highlight
                  **WA_TOP** Top highlight
                  **WA_VERTICAL** Vertical highlight
    
           The return values of many of these routines are not meaningful
           (they are implemented as macro-expanded assignments and simply re‐
           turn their argument).  The SVr4 manual page claims (falsely) that
           these routines always return **1**.
    


## NOTES



           These functions may be macros:
    
                  **attroff** , **wattroff** , **attron** , **wattron** , **attrset** , **wattrset** ,
                  **standend** and **standout**.
    
           Color pair values can only be OR'd with attributes if the pair
           number is less than 256.  The alternate functions such as **col‐**
           **or_set** can pass a color pair value directly.  However, ncurses ABI
           4 and 5 simply OR this value within the alternate functions.  You
           must use ncurses ABI 6 to support more than 256 color pairs.
    


## EXTENSIONS



           This implementation provides the **A_ITALIC** attribute for terminals
           which have the **enter_italics_mode**(**sitm**) and **exit_italics_mode**
           (**ritm**) capabilities.  Italics are not mentioned in X/Open Curses.
           Unlike the other video attributes, **A_ITALIC** is unrelated to the
           **set_attributes** capabilities.  This implementation makes the as‐
           sumption that **exit_attribute_mode** may also reset italics.
    
           Each of the functions added by XSI Curses has a parameter _opts_ ,
           which X/Open Curses still (after more than twenty years) documents
           as reserved for future use, saying that it should be **NULL**.  This
           implementation uses that parameter in ABI 6 for the functions
           which have a color-pair parameter to support _extended color pairs_ :
    
           •   For functions which modify the color, e.g., **wattr_set** and **wat‐**
               **tr_on** , if _opts_ is set it is treated as a pointer to **int** , and
               used to set the color pair instead of the **short** _pair_ parame‐
               ter.
    
           •   For functions which retrieve the color, e.g., **wattr_get** , if
               _opts_ is set it is treated as a pointer to **int** , and used to re‐
               trieve the color pair as an **int** value, in addition to retriev‐
               ing it via the standard pointer to **short** parameter.
    
           •   For functions which turn attributes off, e.g., **wattr_off** , the
               _opts_ parameter is ignored except except to check that it is
               **NULL**.
    


## PORTABILITY



           These functions are supported in the XSI Curses standard, Issue 4.
           The standard defined the dedicated type for highlights, **attr_t** ,
           which was not defined in SVr4 curses.  The functions taking **attr_t**
           arguments were not supported under SVr4.
    
           Very old versions of this library did not force an update of the
           screen when changing the attributes.  Use **touchwin** to force the
           screen to match the updated attributes.
    
           The XSI Curses standard states that whether the traditional func‐
           tions **attron** /**attroff** /**attrset** can manipulate attributes other than
           **A_BLINK** , **A_BOLD** , **A_DIM** , **A_REVERSE** , **A_STANDOUT** , or **A_UNDERLINE** is
           “unspecified”.  Under this implementation as well as SVr4 curses,
           these functions correctly manipulate all other highlights (specif‐
           ically, **A_ALTCHARSET** , **A_PROTECT** , and **A_INVIS**).
    
           XSI Curses added these entry points:
    
                  **attr_get** , **attr_on** , **attr_off** , **attr_set** , **wattr_on** , **wattr_off** ,
                  **wattr_get** , **wattr_set**
    
           The new functions are intended to work with a new series of high‐
           light macros prefixed with **WA_**.  The older macros have direct
           counterparts in the newer set of names:
    
                  **Name            Description**
                  ────────────────────────────────────────────────────────────
                  **WA_NORMAL** Normal display (no highlight)
                  **WA_STANDOUT** Best highlighting mode of the terminal.
                  **WA_UNDERLINE** Underlining
                  **WA_REVERSE** Reverse video
                  **WA_BLINK** Blinking
                  **WA_DIM** Half bright
                  **WA_BOLD** Extra bright or bold
                  **WA_ALTCHARSET** Alternate character set
    
           XSI curses does not assign values to these symbols, nor does it
           state whether or not they are related to the similarly-named
           A_NORMAL, etc.:
    
           •   The XSI curses standard specifies that each pair of corre‐
               sponding **A_** and **WA_** -using functions operates on the same cur‐
               rent-highlight information.
    
           •   However, in some implementations, those symbols have unrelated
               values.
    
               For example, the Solaris _xpg4_ (X/Open) curses declares **attr_t**
               to be an unsigned short integer (16-bits), while **chtype** is a
               unsigned integer (32-bits).  The **WA_** symbols in this case are
               different from the **A_** symbols because they are used for a
               smaller datatype which does not represent **A_CHARTEXT** or **A_COL‐**
               **OR**.
    
               In this implementation (as in many others), the values happen
               to be the same because it simplifies copying information be‐
               tween **chtype** and **cchar_t** variables.
    
           •   Because ncurses's **attr_t** can hold a color pair (in the **A_COLOR**
               field), a call to **wattr_on** , **wattr_off** , or **wattr_set** may alter
               the window's color.  If the color pair information in the at‐
               tribute parameter is zero, no change is made to the window's
               color.
    
               This is consistent with SVr4 curses; X/Open Curses does not
               specify this.
    
           The XSI standard extended conformance level adds new highlights
           **A_HORIZONTAL** , **A_LEFT** , **A_LOW** , **A_RIGHT** , **A_TOP** , **A_VERTICAL**(and cor‐
           responding **WA_** macros for each).  As of August 2013, no known ter‐
           minal provides these highlights (i.e., via the **sgr1** capability).
    


## RETURN VALUE



           All routines return the integer **OK** on success, or **ERR** on failure.
    
           X/Open does not define any error conditions.
    
           This implementation
    
           •   returns an error if the window pointer is null.
    
           •   returns an error if the color pair parameter for **wcolor_set** is
               outside the range 0..COLOR_PAIRS-1.
    
           •   does not return an error if either of the parameters of **wat‐**
               **tr_get** used for retrieving attribute or color-pair values is
               **NULL**.
    
           Functions with a “mv” prefix first perform a cursor movement using
           **wmove** , and return an error if the position is outside the window,
           or if the window pointer is null.
    


* * *