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.


Window attributes

       The attr_set and wattr_set functions set the  current  at-
       tributes  of  the given window to attrs, with color speci-
       fied by pair.  X/Open specified  an  additional  parameter
       opts which is unused in all implementations.

       Use  attr_get and 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)).  The opts argument is not presently used,
       but is reserved for the future (leave it NULL).


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.  The parameter opts is re-
       served for future use; applications  must  supply  a  null
       pointer.


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


PORTABILITY

       These functions are supported in the XSI Curses  standard,
       Issue  4.   The  standard  defined  the dedicated type for
       highlights, attr_t, which is not defined in  SVr4  curses.
       The  functions  taking  attr_t arguments are not supported
       under SVr4.

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

       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.

       XSI Curses added the new entry points, attr_get,  attr_on,
       attr_off,  attr_set,  wattr_on, wattr_off, wattr_get, wat-
       tr_set.  These 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

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

       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)