X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_attr.3x.html;h=b0bb4980f94e33c5ca908cd2478e0005d3808eb1;hb=a8e3f06ac309504143cd56ac9ec55889bfdf4914;hp=d76dd9b79d9044a3de85673518f373239d79bbe6;hpb=a3725e39272393790e32a083fd7391aad607828d;p=ncurses.git diff --git a/doc/html/man/curs_attr.3x.html b/doc/html/man/curs_attr.3x.html index d76dd9b7..b0bb4980 100644 --- a/doc/html/man/curs_attr.3x.html +++ b/doc/html/man/curs_attr.3x.html @@ -1,7 +1,7 @@ @@ -46,115 +58,116 @@ - -

NAME

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

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

+

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 color_set(short color_pair_number, void* opts);
-       int wcolor_set(WINDOW *win, short color_pair_number,
-             void* opts);
+
+       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);
-       int attr_get(attr_t *attrs, short *pair, void *opts);
-       int wattr_get(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 attr_set(attr_t attrs, short pair, void *opts);
-       int wattr_set(WINDOW *win, attr_t attrs, short pair,  void
-       *opts);
-       int chgat(int n, attr_t attr, short color,
-             const void *opts);
-       int wchgat(WINDOW *win, int n, attr_t attr,
-             short color, const void *opts);
-       int mvchgat(int y, int x, int n, attr_t attr,
-             short color, const void *opts);
-       int mvwchgat(WINDOW *win, int y, int x, int n,
-             attr_t attr, short color, const void *opts);
 
 
-
-

DESCRIPTION

+

DESCRIPTION

        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 wadd-
-       ch, 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.
+       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.
 
-
-

attrset

-       The  routine  attrset  sets  the current attributes of the
-       given window to attrs.  The routine attroff turns off  the
-       named  attributes  without turning any other attributes on
-       or off.  The routine attron turns on the named  attributes
-       without affecting any others.  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.
-
-       The attrset and related routines do  not  affect  the  at-
-       tributes  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.
 
 
-
-

attr_set

-       The attrset routine is actually a legacy feature predating
-       SVr4 curses but kept in X/Open Curses for the same  reason
-       that  SVr4  curses kept it: compatbility.  The routine at-
-       tr_set provides for passing a color-pair parameter.
+

Window attributes

+       There are two sets of functions:
 
-       The remaining attr_* functions operate  exactly  like  the
-       corresponding attr* functions, except that they take argu-
-       ments of type attr_t rather than int.
+       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.
 
-
-

color_set

-       The routine color_set sets the current color of the  given
-       window  to the foreground/background combination described
-       by the color_pair_number.  The parameter opts is  reserved
-       for future use, applications must supply a null pointer.
+       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.
 
-
-

attr_get

-       The  routine  wattr_get  returns the current attribute and
-       color pair for the given window; attr_get returns the cur-
-       rent attribute and color pair for stdscr.
+       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)).
 
 
-
-

chgat

+

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-
@@ -162,36 +175,52 @@
        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  argument is a color-pair index (as in the first ar-
-       gument of init_pair, see curs_color(3x)).  The opts  argu-
-       ment is not presently used, but is reserved for the future
-       (leave it NULL).
+       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)).
 
-
-

Attributes

+
+

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
-
-              COLOR_PAIR(n)   Color-pair number n
+       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
@@ -206,61 +235,85 @@
               WA_TOP          Top highlight
               WA_VERTICAL     Vertical highlight
 
-       For consistency
-
-       The following macro is the reverse of COLOR_PAIR(n):
-
-       PAIR_NUMBER(attrs) Returns the pair number associated
-                          with the COLOR_PAIR(n) attribute.
-
-       The  return values of many of these routines are not mean-
+       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
+       and simply return their argument).  The SVr4  manual  page
        claims (falsely) that these routines always return 1.
 
 
-
-

NOTES

-       Note that attroff,  wattroff,  attron,  wattron,  attrset,
-       wattrset, standend and standout may be macros.
-
-       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
+

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

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
+

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,
+       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, I_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 these entry points:
 
-       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:
+              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
               ------------------------------------------------------------
@@ -273,10 +326,6 @@
               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.
@@ -288,26 +337,29 @@
        (i.e., via the sgr1 capability).
 
 
-
-

RETURN VALUE

+

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.  The wcolor_set function returns an error if  the
-       color   pair   parameter  is  outside  the  range  0..COL-
-       OR_PAIRS-1.  This implementation  also  provides  getattrs
-       for compatibility with older versions of curses.
+       This implementation
 
-       Functions  with a "mv" prefix first perform a cursor move-
-       ment using wmove, and return an error if the  position  is
+       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

+

SEE ALSO

        curses(3x), curs_addch(3x), curs_addstr(3x),
        curs_bkgd(3x), curs_printw(3x), curs_variables(3x)
 
@@ -321,15 +373,16 @@
 
  • SYNOPSIS
  • DESCRIPTION
  • +
  • VIDEO ATTRIBUTES
  • NOTES
  • +
  • EXTENSIONS
  • PORTABILITY
  • RETURN VALUE
  • SEE ALSO