http://invisible-island.net/ncurses/man/


curs_attr 3x

curs_attr(3x)                                             curs_attr(3x)




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 window, which then apply to all characters that  are
       written  into the window with waddch, waddstr and wprintw.
       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.

       These routines do not  affect  the  attributes  used  when
       erasing  portions  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:

       o   functions  for  manipulating the window attributes and
           color: wattr_set and wattr_get.

       o   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., values OR'd together in attr, without affecting oth-
       er 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

       Most of the window attribute routines  are  extensions  of
       older routines which assume that color pairs are OR'd into
       the attribute parameter.  These  older  routines  use  the
       same name, omitting an underscore (_).

       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
       corresponding attr_* functions, except that they take  ar-
       guments of type int rather than attr_t.

       There  is  no  corresponding  attrget  function as such in
       X/Open Curses, 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 per-
       form 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.  The wchgat  func-
       tion 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  routine  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

       o   they have well established legacy use, and

       o   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_add-
       ch(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

       These video attributes are supported by attr_on and relat-
       ed functions (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  mean-
       ingful (they are implemented as macro-expanded assignments
       and simply return 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, wat-
              trset, 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 color_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 ex-
       it_italics_mode (ritm) capabilities.  Italics are not men-
       tioned in X/Open  Curses.   Unlike  the  other  video  at-
       tributes,  A_ITALIC is unrelated to the set_attributes ca-
       pabilities.  This implementation makes the assumption 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  parame-
       ter in ABI 6 for the functions which have a color-pair pa-
       rameter to support extended color pairs:

       o   For functions which modify the color, e.g., wattr_set,
           if  opts is set it is treated as a pointer to int, and
           used to set the color pair instead of the  short  pair
           parameter.

       o   For  functions  which  retrieve  the color, e.g., wat-
           tr_get, if opts is set it is treated as a  pointer  to
           int,  and  used  to  retrieve the color pair as an int
           value, in addition  retrieving  it  via  the  standard
           pointer to short parameter.

       The remaining functions which have opts, but do not manip-
       ulate color, e.g., wattr_on and wattr_off are not used  by
       this implementation except to check that they are 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 tradition-
       al functions  attron/attroff/attrset  can  manipulate  at-
       tributes  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  (specifically,
       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  highlight  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

       The XSI curses standard specifies that each pair of corre-
       sponding  A_  and WA_-using functions operates on the same
       current-highlight information.

       The XSI standard extended conformance level adds new high-
       lights A_HORIZONTAL, A_LEFT, A_LOW, A_RIGHT, A_TOP, A_VER-
       TICAL (and corresponding WA_ macros for each).  As of  Au-
       gust  2013,  no  known  terminal 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

       o   returns an error if the window pointer is null.

       o   returns an error if the color pair parameter for wcol-
           or_set is outside the range 0..COLOR_PAIRS-1.

       o   does not return an error if either of  the  parameters
           of  wattr_get  used for retrieving attribute or color-
           pair values is NULL.

       Functions with a "mv" prefix first perform a cursor  move-
       ment  using  wmove, and return an error if the position is
       outside the window, or if the window pointer is null.


SEE ALSO

       curses(3x), curs_addch(3x), curs_addstr(3x),
       curs_bkgd(3x), curs_printw(3x), curs_variables(3x)



                                                          curs_attr(3x)