]> ncurses.scripts.mit.edu Git - ncurses.git/blobdiff - doc/html/man/curs_color.3x.html
ncurses 6.5 - patch 20240504
[ncurses.git] / doc / html / man / curs_color.3x.html
index 1eaf1e8c5053c644f6dd8f079ae7e56757c450f6..d84a5732540abd87d3938fce4588c19cdf57b52f 100644 (file)
@@ -1,6 +1,6 @@
 <!--
   ****************************************************************************
 <!--
   ****************************************************************************
-  * Copyright 2018-2022,2023 Thomas E. Dickey                                *
+  * Copyright 2018-2023,2024 Thomas E. Dickey                                *
   * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_color.3x,v 1.87 2023/10/21 10:28:36 tom Exp @
+  * @Id: curs_color.3x,v 1.100 2024/04/20 21:24:19 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 <HEAD>
 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 <HEAD>
 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
-<TITLE>curs_color 3x 2023-10-21 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_color 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
 <link rel="author" href="mailto:bug-ncurses@gnu.org">
 
 </HEAD>
 <BODY>
 <link rel="author" href="mailto:bug-ncurses@gnu.org">
 
 </HEAD>
 <BODY>
-<H1 class="no-header">curs_color 3x 2023-10-21 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_color 3x 2024-04-20 ncurses 6.5 Library calls</H1>
 <PRE>
 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>                   Library calls                  <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 
 <PRE>
 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>                   Library calls                  <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 
        <STRONG>start_color</STRONG>,   <STRONG>has_colors</STRONG>,   <STRONG>can_change_color</STRONG>,  <STRONG>init_pair</STRONG>,  <STRONG>init_color</STRONG>,
        <STRONG>init_extended_pair</STRONG>, <STRONG>init_extended_color</STRONG>,  <STRONG>color_content</STRONG>,  <STRONG>pair_content</STRONG>,
        <STRONG>extended_color_content</STRONG>,    <STRONG>extended_pair_content</STRONG>,    <STRONG>reset_color_pairs</STRONG>,
        <STRONG>start_color</STRONG>,   <STRONG>has_colors</STRONG>,   <STRONG>can_change_color</STRONG>,  <STRONG>init_pair</STRONG>,  <STRONG>init_color</STRONG>,
        <STRONG>init_extended_pair</STRONG>, <STRONG>init_extended_color</STRONG>,  <STRONG>color_content</STRONG>,  <STRONG>pair_content</STRONG>,
        <STRONG>extended_color_content</STRONG>,    <STRONG>extended_pair_content</STRONG>,    <STRONG>reset_color_pairs</STRONG>,
-       <STRONG>COLOR_PAIR</STRONG>, <STRONG>PAIR_NUMBER</STRONG> - manipulate terminal colors with <EM>curses</EM>
+       <STRONG>COLOR_PAIR</STRONG>, <STRONG>PAIR_NUMBER</STRONG>, <STRONG>COLORS</STRONG>, <STRONG>COLOR_PAIRS</STRONG>,  <STRONG>COLOR_BLACK</STRONG>,  <STRONG>COLOR_RED</STRONG>,
+       <STRONG>COLOR_GREEN</STRONG>,   <STRONG>COLOR_YELLOW</STRONG>,   <STRONG>COLOR_BLUE</STRONG>,  <STRONG>COLOR_MAGENTA</STRONG>,  <STRONG>COLOR_CYAN</STRONG>,
+       <STRONG>COLOR_WHITE</STRONG> - manipulate terminal colors with <EM>curses</EM>
 
 
 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
 
 
 
 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
 
+       <EM>/*</EM> <EM>variables</EM> <EM>*/</EM>
+       <STRONG>int</STRONG> <STRONG>COLOR_PAIRS;</STRONG>
+       <STRONG>int</STRONG> <STRONG>COLORS;</STRONG>
+
        <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
 
        <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
        <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
 
        <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
        <STRONG>void</STRONG> <STRONG>reset_color_pairs(void);</STRONG>
 
        <STRONG>int</STRONG> <STRONG>COLOR_PAIR(int</STRONG> <EM>n</EM><STRONG>);</STRONG>
        <STRONG>void</STRONG> <STRONG>reset_color_pairs(void);</STRONG>
 
        <STRONG>int</STRONG> <STRONG>COLOR_PAIR(int</STRONG> <EM>n</EM><STRONG>);</STRONG>
-       <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM><STRONG>);</STRONG>
+       <STRONG>PAIR_NUMBER(int</STRONG> <EM>attr</EM><STRONG>);</STRONG>
 
 
 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 
 </PRE><H3><a name="h3-Overview">Overview</a></H3><PRE>
 
 
 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 
 </PRE><H3><a name="h3-Overview">Overview</a></H3><PRE>
-       <EM>curses</EM> supports color attributes on terminals with that capability.  To
-       use  these  routines  <STRONG>start_color</STRONG>  must  be called, usually right after
-       <STRONG>initscr</STRONG>.  Colors are always used in pairs (referred to as color-pairs).
-       A  color-pair  consists  of  a  foreground color (for characters) and a
-       background color (for the blank  field  on  which  the  characters  are
-       displayed).   A  programmer  initializes  a color-pair with the routine
-       <STRONG>init_pair</STRONG>.  After it has been initialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>) can be used to
-       convert the pair to a video attribute.
-
-       If  a  terminal is capable of redefining colors, the programmer can use
-       the routine <STRONG>init_color</STRONG> to  change  the  definition  of  a  color.   The
-       routines   <STRONG>has_colors</STRONG>   and  <STRONG>can_change_color</STRONG>  return  <STRONG>TRUE</STRONG>  or  <STRONG>FALSE</STRONG>,
-       depending on whether the terminal has color  capabilities  and  whether
-       the programmer can change the colors.  The routine <STRONG>color_content</STRONG> allows
-       a programmer to extract the amounts of red, green, and blue  components
-       in  an initialized color.  The routine <STRONG>pair_content</STRONG> allows a programmer
-       to find out how a given color-pair is currently defined.
+       <EM>curses</EM> supports color attributes on  terminals  with  that  capability.
+       Call  <STRONG>start_color</STRONG>  (typically  right  after <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>) to enable this
+       feature.  Colors are always used in pairs.   A  <EM>color</EM>  <EM>pair</EM>  couples  a
+       foreground  color  for characters with a background color for the blank
+       field on which characters are rendered.  <STRONG>init_pair</STRONG> initializes a  color
+       pair.   The  macro  <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>)  can then convert the pair to a video
+       attribute.
+
+       If  a  terminal  has  the  relevant  capability,   <STRONG>init_color</STRONG>   permits
+       (re)definition of a color.  <STRONG>has_colors</STRONG> and <STRONG>can_change_color</STRONG> return <STRONG>TRUE</STRONG>
+       or <STRONG>FALSE</STRONG>, depending on whether the terminal has  color  capability  and
+       whether  the  programmer  can change the colors.  <STRONG>color_content</STRONG> permits
+       extraction of the red, green, and blue  components  of  an  initialized
+       color.   <STRONG>pair_content</STRONG>  permits  discovery  of  a  color  pair's current
+       definition.
 
 
 
 
-</PRE><H3><a name="h3-Color-Rendering">Color Rendering</a></H3><PRE>
-       The  <EM>curses</EM>  library  combines  these  inputs  to  produce  the  actual
-       foreground and background colors shown on the screen:
+</PRE><H3><a name="h3-Rendering">Rendering</a></H3><PRE>
+       <EM>curses</EM> combines the following data to render a character cell.  Any  of
+       them can include color information.
 
 
-       <STRONG>o</STRONG>   per-character video attributes (e.g., via <STRONG>waddch</STRONG>),
+       <STRONG>o</STRONG>   <EM>curses</EM> character attributes, as from <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> or <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>
 
 
-       <STRONG>o</STRONG>   the window attribute (e.g., by <STRONG>wattrset</STRONG>), and
+       <STRONG>o</STRONG>   window attributes, as from <STRONG><A HREF="curs_attr.3x.html">wattrset(3x)</A></STRONG> or <STRONG><A HREF="curs_attr.3x.html">wattr_set(3x)</A></STRONG>
 
 
-       <STRONG>o</STRONG>   the background character (e.g., <STRONG>wbkgdset</STRONG>).
+       <STRONG>o</STRONG>   window  background  character  attributes,  as from <STRONG><A HREF="curs_bkgd.3x.html">wbkgdset(3x)</A></STRONG> or
+           <STRONG><A HREF="curs_bkgrnd.3x.html">wbkgrndset(3x)</A></STRONG>
 
 
-       Per-character  and  window  attributes  are  usually set by a parameter
-       containing  video  attributes  including  a  color  pair  value.   Some
-       functions such as <STRONG>wattr_set</STRONG> use a separate parameter which is the color
-       pair number.
+       Per-character and window attributes are usually set through a  function
+       parameter  containing  attributes  including  a color pair value.  Some
+       functions,  such  as  <STRONG>wattr_set</STRONG>,  use  a  separate  color  pair  number
+       parameter.
 
 
-       The background character is a special case:  it  includes  a  character
-       value, just as if it were passed to <STRONG>waddch</STRONG>.
+       The  background  character  is  a special case: it includes a character
+       code, just as if it were passed to <STRONG>waddch</STRONG>.
 
 
-       The  <EM>curses</EM> library does the actual work of combining these color pairs
+       The <EM>curses</EM> library does the actual work of combining these color  pairs
        in an internal function called from <STRONG>waddch</STRONG>:
 
        <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>blank</EM>, and it uses the special
        in an internal function called from <STRONG>waddch</STRONG>:
 
        <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>blank</EM>, and it uses the special
 
            <STRONG>o</STRONG>   <EM>curses</EM> next checks the window attribute.
 
 
            <STRONG>o</STRONG>   <EM>curses</EM> next checks the window attribute.
 
-           <STRONG>o</STRONG>   If  the window attribute does not use color pair 0, <EM>curses</EM> uses
+           <STRONG>o</STRONG>   If the window attribute does not use color pair 0, <EM>curses</EM>  uses
                the color pair from the window attribute.
 
            <STRONG>o</STRONG>   Otherwise, <EM>curses</EM> uses the background character.
 
                the color pair from the window attribute.
 
            <STRONG>o</STRONG>   Otherwise, <EM>curses</EM> uses the background character.
 
-       <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>not</EM> <EM>blank</EM>, or it does not  use
-           the  special  color  pair 0, <EM>curses</EM> prefers the color pair from the
-           parameter, if it  is  nonzero.   Otherwise,  it  tries  the  window
+       <STRONG>o</STRONG>   If  the parameter passed to <STRONG>waddch</STRONG> is <EM>not</EM> <EM>blank</EM>, or it does not use
+           the special color pair 0, <EM>curses</EM> prefers the color  pair  from  the
+           parameter,  if  it  is  nonzero.   Otherwise,  it  tries the window
            attribute next, and finally the background character.
 
            attribute next, and finally the background character.
 
-       Some  <EM>curses</EM>  functions  such  as  <STRONG>wprintw</STRONG>  call  <STRONG>waddch</STRONG>.  Those do not
-       combine its parameter with a color pair.  Consequently those calls  use
+       Some <EM>curses</EM> functions such  as  <STRONG>wprintw</STRONG>  call  <STRONG>waddch</STRONG>.   Those  do  not
+       combine  its parameter with a color pair.  Consequently those calls use
        only the window attribute or the background character.
 
 
        only the window attribute or the background character.
 
 
              <STRONG>COLOR_CYAN</STRONG>
              <STRONG>COLOR_WHITE</STRONG>
 
              <STRONG>COLOR_CYAN</STRONG>
              <STRONG>COLOR_WHITE</STRONG>
 
-       Some  terminals  support  more than the eight (8) "ANSI" colors.  There
+       Some terminals support more than the eight (8)  "ANSI"  colors.   There
        are no standard names for those additional colors.
 
 
 </PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE>
 
 </PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
        are no standard names for those additional colors.
 
 
 </PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE>
 
 </PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
-       is initialized by <STRONG>start_color</STRONG> to  the  maximum  number  of  colors  the
+       is  initialized  by  <STRONG>start_color</STRONG>  to  the  maximum number of colors the
        terminal can support.
 
 
 </PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
        terminal can support.
 
 
 </PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
-       is  initialized by <STRONG>start_color</STRONG> to the maximum number of color pairs the
-       terminal can support.
+       is initialized by <STRONG>start_color</STRONG> to the maximum number of color pairs  the
+       terminal can support.  Often, its value is the product <STRONG>COLORS</STRONG> x <STRONG>COLORS</STRONG>,
+       but this is not always true.
+
+       <STRONG>o</STRONG>   A few terminals use the HLS color space  (see  <STRONG>start_color</STRONG>  below),
+           ignoring this rule; and
+
+       <STRONG>o</STRONG>   terminals  supporting  a  large number of colors are limited to the
+           number of color pairs that a <EM>signed</EM> <EM>short</EM> value can represent.
 
 
 </PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE>
        routine right after <STRONG>initscr</STRONG>.  <STRONG>start_color</STRONG> does this:
 
        <STRONG>o</STRONG>   It   initializes  two  global  variables,  <STRONG>COLORS</STRONG>  and  <STRONG>COLOR_PAIRS</STRONG>
        routine right after <STRONG>initscr</STRONG>.  <STRONG>start_color</STRONG> does this:
 
        <STRONG>o</STRONG>   It   initializes  two  global  variables,  <STRONG>COLORS</STRONG>  and  <STRONG>COLOR_PAIRS</STRONG>
-           (respectively defining the maximum number of colors and color-pairs
+           (respectively defining the maximum number of colors and color pairs
            the terminal can support).
 
        <STRONG>o</STRONG>   It  initializes  the special color pair <STRONG>0</STRONG> to the default foreground
            the terminal can support).
 
        <STRONG>o</STRONG>   It  initializes  the special color pair <STRONG>0</STRONG> to the default foreground
            alter the internal table along with the terminal's color.
 
        These limits apply to color values and  color  pairs.   Values  outside
            alter the internal table along with the terminal's color.
 
        These limits apply to color values and  color  pairs.   Values  outside
-       these limits are not legal, and may result in a runtime error:
+       these limits are not valid, and may result in a runtime error:
 
        <STRONG>o</STRONG>   <STRONG>COLORS</STRONG>   corresponds   to   the   terminal   database's  <STRONG>max_colors</STRONG>
            capability, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 
        <STRONG>o</STRONG>   <STRONG>COLORS</STRONG>   corresponds   to   the   terminal   database's  <STRONG>max_colors</STRONG>
            capability, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
        <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG>  corresponds  to  the  terminal  database's   <STRONG>max_pairs</STRONG>
            capability, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 
        <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG>  corresponds  to  the  terminal  database's   <STRONG>max_pairs</STRONG>
            capability, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 
-       <STRONG>o</STRONG>   legal  color  pair  values  are  in  the  range <STRONG>1</STRONG> to <STRONG>COLOR_PAIRS-1</STRONG>,
+       <STRONG>o</STRONG>   valid  color  pair  values  are  in  the  range <STRONG>1</STRONG> to <STRONG>COLOR_PAIRS-1</STRONG>,
            inclusive.
 
        <STRONG>o</STRONG>   color pair <STRONG>0</STRONG> is special; it denotes "no color".
            inclusive.
 
        <STRONG>o</STRONG>   color pair <STRONG>0</STRONG> is special; it denotes "no color".
 
 
 </PRE><H3><a name="h3-init_pair">init_pair</a></H3><PRE>
 
 
 </PRE><H3><a name="h3-init_pair">init_pair</a></H3><PRE>
-       The <STRONG>init_pair</STRONG> routine changes the definition of a color-pair.  It takes
-       three arguments: the number  of  the  color-pair  to  be  changed,  the
+       The <STRONG>init_pair</STRONG> routine changes the definition of a color pair.  It takes
+       three arguments: the number of  the  color  pair  to  be  changed,  the
        foreground color number, and the background color number.  For portable
        applications:
 
        foreground color number, and the background color number.  For portable
        applications:
 
-       <STRONG>o</STRONG>   The first argument must be a legal color pair  value.   If  default
+       <STRONG>o</STRONG>   The first argument must be a valid color pair  value.   If  default
            colors  are  used  (see  <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>) the upper limit is
            adjusted to allow for extra pairs which  use  a  default  color  in
            foreground and/or background.
 
            colors  are  used  (see  <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>) the upper limit is
            adjusted to allow for extra pairs which  use  a  default  color  in
            foreground and/or background.
 
-       <STRONG>o</STRONG>   The second and third arguments must be legal color values.
+       <STRONG>o</STRONG>   The second and third arguments must be valid color values.
 
 
-       If  the  color-pair was previously initialized, the screen is refreshed
-       and  all  occurrences  of  that  color-pair  are  changed  to  the  new
+       If  the  color pair was previously initialized, the screen is refreshed
+       and all  occurrences  of  that  color  pair  are  changed  to  the  new
        definition.
 
        definition.
 
-       As  an  extension,  ncurses  allows  you  to  set  color pair <STRONG>0</STRONG> via the
+       As  an  extension,  <EM>ncurses</EM>  allows  you  to  set  color pair <STRONG>0</STRONG> via the
        <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> routine, or to specify  the  use  of  default
        colors (color number <STRONG>-1</STRONG>) if you first invoke the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>
        routine.
        <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> routine, or to specify  the  use  of  default
        colors (color number <STRONG>-1</STRONG>) if you first invoke the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>
        routine.
 
 </PRE><H3><a name="h3-init_extended_pair">init_extended_pair</a></H3><PRE>
        Because <STRONG>init_pair</STRONG> uses signed <STRONG>short</STRONG>s for its  parameters,  that  limits
 
 </PRE><H3><a name="h3-init_extended_pair">init_extended_pair</a></H3><PRE>
        Because <STRONG>init_pair</STRONG> uses signed <STRONG>short</STRONG>s for its  parameters,  that  limits
-       color-pairs   and  color-values  to  32767  on  modern  hardware.   The
-       extension <STRONG>init_extended_pair</STRONG> uses <STRONG>int</STRONG>s for the  color-pair  and  color-
+       color  pairs  and  color-values  to  32767  on  modern  hardware.   The
+       extension <STRONG>init_extended_pair</STRONG> uses <STRONG>int</STRONG>s for the color  pair  and  color-
        value, allowing a larger number of colors to be supported.
 
 
        value, allowing a larger number of colors to be supported.
 
 
        four arguments: the number of the color to be changed followed by three
        RGB values (for the amounts of red, green, and blue components).
 
        four arguments: the number of the color to be changed followed by three
        RGB values (for the amounts of red, green, and blue components).
 
-       <STRONG>o</STRONG>   The  first argument must be a legal color value; default colors are
+       <STRONG>o</STRONG>   The  first argument must be a valid color value; default colors are
            not allowed here.  (See the section <STRONG>Colors</STRONG> for  the  default  color
            index.)
 
            not allowed here.  (See the section <STRONG>Colors</STRONG> for  the  default  color
            index.)
 
        storing the information about the  amounts  of  red,  green,  and  blue
        components in the given color.
 
        storing the information about the  amounts  of  red,  green,  and  blue
        components in the given color.
 
-       <STRONG>o</STRONG>   The  first  argument  must  be a legal color value, i.e., <STRONG>0</STRONG> through
+       <STRONG>o</STRONG>   The  first  argument  must  be a valid color value, i.e., <STRONG>0</STRONG> through
            <STRONG>COLORS-1</STRONG>, inclusive.
 
        <STRONG>o</STRONG>   The values that are stored at the addresses pointed to by the  last
            <STRONG>COLORS-1</STRONG>, inclusive.
 
        <STRONG>o</STRONG>   The values that are stored at the addresses pointed to by the  last
 
 </PRE><H3><a name="h3-pair_content">pair_content</a></H3><PRE>
        The <STRONG>pair_content</STRONG> routine allows programmers to find out what  colors  a
 
 </PRE><H3><a name="h3-pair_content">pair_content</a></H3><PRE>
        The <STRONG>pair_content</STRONG> routine allows programmers to find out what  colors  a
-       given  color-pair consists of.  It requires three arguments: the color-
+       given  color  pair consists of.  It requires three arguments: the color
        pair number, and two addresses of <STRONG>short</STRONG>s for storing the foreground and
        the background color numbers.
 
        pair number, and two addresses of <STRONG>short</STRONG>s for storing the foreground and
        the background color numbers.
 
-       <STRONG>o</STRONG>   The  first argument must be a legal color value, i.e., in the range
+       <STRONG>o</STRONG>   The  first argument must be a valid color value, i.e., in the range
            <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>, inclusive.
 
        <STRONG>o</STRONG>   The values that are stored at  the  addresses  pointed  to  by  the
            <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>, inclusive.
 
        <STRONG>o</STRONG>   The values that are stored at  the  addresses  pointed  to  by  the
 
 </PRE><H3><a name="h3-extended_pair_content">extended_pair_content</a></H3><PRE>
        Because <STRONG>pair_content</STRONG> uses signed <STRONG>short</STRONG>s for its parameters, that limits
 
 </PRE><H3><a name="h3-extended_pair_content">extended_pair_content</a></H3><PRE>
        Because <STRONG>pair_content</STRONG> uses signed <STRONG>short</STRONG>s for its parameters, that limits
-       color-pair and color-values to 32767 on modern hardware.  The extension
+       color pair and color-values to 32767 on modern hardware.  The extension
        <STRONG>extended_pair_content</STRONG> uses <STRONG>int</STRONG>s for the color pair  and  for  returning
        the  foreground  and  background  colors,  allowing  a larger number of
        colors to be supported.
 
 
 </PRE><H3><a name="h3-reset_color_pairs">reset_color_pairs</a></H3><PRE>
        <STRONG>extended_pair_content</STRONG> uses <STRONG>int</STRONG>s for the color pair  and  for  returning
        the  foreground  and  background  colors,  allowing  a larger number of
        colors to be supported.
 
 
 </PRE><H3><a name="h3-reset_color_pairs">reset_color_pairs</a></H3><PRE>
-       The extension <STRONG>reset_color_pairs</STRONG> tells ncurses to  discard  all  of  the
-       color-pair  information  which was set with <STRONG>init_pair</STRONG>.  It also touches
+       The extension <STRONG>reset_color_pairs</STRONG> tells <EM>ncurses</EM> to  discard  all  of  the
+       color  pair  information which was set with <STRONG>init_pair</STRONG>.  It also touches
        the current- and standard-screens, allowing an  application  to  switch
        color palettes rapidly.
 
 
        the current- and standard-screens, allowing an  application  to  switch
        color palettes rapidly.
 
 
-</PRE><H3><a name="h3-PAIR_NUMBER">PAIR_NUMBER</a></H3><PRE>
-       <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM>)  extracts  the  color value from its <EM>attrs</EM> parameter
-       and returns it as a color pair number.
+</PRE><H3><a name="h3-COLOR_PAIR">COLOR_PAIR</a></H3><PRE>
+       <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an attribute.  Attributes
+       can hold color pairs in the range 0 to 255.  If you need a  color  pair
+       larger  than  that, you must use functions such as <STRONG>attr_set</STRONG> (which pass
+       the color  pair  as  a  separate  parameter)  rather  than  the  legacy
+       functions such as <STRONG>attrset</STRONG>.
 
 
 
 
-</PRE><H3><a name="h3-COLOR_PAIR">COLOR_PAIR</a></H3><PRE>
-       Its inverse <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an attribute.
-       Attributes  can  hold color pairs in the range 0 to 255.  If you need a
-       color pair larger than that, you must use functions  such  as  <STRONG>attr_set</STRONG>
-       (which  pass  the  color  pair as a separate parameter) rather than the
-       legacy functions such as <STRONG>attrset</STRONG>.
+</PRE><H3><a name="h3-PAIR_NUMBER">PAIR_NUMBER</a></H3><PRE>
+       <STRONG>PAIR_NUMBER(</STRONG><EM>attr</EM>)   extracts   the  color  information  from  its  <EM>attr</EM>
+       parameter and returns it as a color pair  number;  it  is  the  inverse
+       operation of <STRONG>COLOR_PAIR</STRONG>.
 
 
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
        The routines <STRONG>can_change_color</STRONG> and <STRONG>has_colors</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
 
 
 
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
        The routines <STRONG>can_change_color</STRONG> and <STRONG>has_colors</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
 
-       All other routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG>  (SVr4
-       specifies  only  "an  integer  value  other  than <STRONG>ERR</STRONG>") upon successful
+       All  other routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
+       specifies only "an integer  value  other  than  <STRONG>ERR</STRONG>")  upon  successful
        completion.
 
        completion.
 
-       X/Open defines no error conditions.   SVr4  does  document  some  error
+       X/Open  defines  no  error  conditions.   SVr4 does document some error
        conditions which apply in general:
 
        <STRONG>o</STRONG>   This implementation will return <STRONG>ERR</STRONG> on attempts to use color values
        conditions which apply in general:
 
        <STRONG>o</STRONG>   This implementation will return <STRONG>ERR</STRONG> on attempts to use color values
-           outside the range <STRONG>0</STRONG> to <STRONG>COLORS</STRONG>-1  (except  for  the  default  colors
-           extension),   or   use   color   pairs   outside  the  range  <STRONG>0</STRONG>  to
+           outside  the  range  <STRONG>0</STRONG>  to  <STRONG>COLORS</STRONG>-1 (except for the default colors
+           extension),  or  use  color  pairs   outside   the   range   <STRONG>0</STRONG>   to
            <STRONG>COLOR_PAIRS-1</STRONG>.
 
            Color values used in <STRONG>init_color</STRONG> must be in the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.
 
            <STRONG>COLOR_PAIRS-1</STRONG>.
 
            Color values used in <STRONG>init_color</STRONG> must be in the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.
 
-           An error is returned from all functions if  the  terminal  has  not
+           An  error  is  returned  from all functions if the terminal has not
            been initialized.
 
            been initialized.
 
-           An  error is returned from secondary functions such as <STRONG>init_pair</STRONG> if
+           An error is returned from secondary functions such as <STRONG>init_pair</STRONG>  if
            <STRONG>start_color</STRONG> was not called.
 
            <STRONG>start_color</STRONG> was not called.
 
-       <STRONG>o</STRONG>   SVr4  does  much  the  same,  except  that  it  returns  <STRONG>ERR</STRONG>   from
-           <STRONG>pair_content</STRONG>  if  the pair was not initialized using <STRONG>init_pairs</STRONG> and
-           it returns <STRONG>ERR</STRONG> from <STRONG>color_content</STRONG> if the terminal does not  support
+       <STRONG>o</STRONG>   SVr4   does  much  the  same,  except  that  it  returns  <STRONG>ERR</STRONG>  from
+           <STRONG>pair_content</STRONG> if the pair was not initialized using  <STRONG>init_pairs</STRONG>  and
+           it  returns <STRONG>ERR</STRONG> from <STRONG>color_content</STRONG> if the terminal does not support
            changing colors.
 
            This implementation does not return <STRONG>ERR</STRONG> for either case.
            changing colors.
 
            This implementation does not return <STRONG>ERR</STRONG> for either case.
 
           <STRONG>init_color</STRONG>
                returns an error if the terminal does not support this feature,
 
           <STRONG>init_color</STRONG>
                returns an error if the terminal does not support this feature,
-               e.g., if the <STRONG>initialize_color</STRONG> capability  is  absent  from  the
+               e.g.,  if  the  <STRONG>initialize_color</STRONG>  capability is absent from the
                terminal description.
 
           <STRONG>start_color</STRONG>
                terminal description.
 
           <STRONG>start_color</STRONG>
 
 
 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
-       In  the  <EM>ncurses</EM>  implementation,  there is a separate color activation
-       flag, color palette, color  pairs  table,  and  associated  <STRONG>COLORS</STRONG>  and
-       <STRONG>COLOR_PAIRS</STRONG>  counts  for  each  screen;  the  <STRONG>start_color</STRONG> function only
-       affects the current screen.   The  SVr4/XSI  interface  is  not  really
-       designed  with  this  in mind, and historical implementations may use a
+       In the <EM>ncurses</EM> implementation, there is  a  separate  color  activation
+       flag,  color  palette,  color  pairs  table,  and associated <STRONG>COLORS</STRONG> and
+       <STRONG>COLOR_PAIRS</STRONG> counts for  each  screen;  the  <STRONG>start_color</STRONG>  function  only
+       affects  the  current  screen.   The  SVr4/XSI  interface is not really
+       designed with this in mind, and historical implementations  may  use  a
        single shared color palette.
 
        single shared color palette.
 
-       Setting an implicit background color via  a  color  pair  affects  only
-       character  cells  that  a character write operation explicitly touches.
-       To change the background color used when parts of a window are  blanked
+       Setting  an  implicit  background  color  via a color pair affects only
+       character cells that a character write  operation  explicitly  touches.
+       To  change the background color used when parts of a window are blanked
        by erasing or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
 
        by erasing or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
 
-       Several  caveats  apply  on  older x86 machines (e.g., i386, i486) with
+       Several caveats apply on older x86 machines  (e.g.,  i386,  i486)  with
        VGA-compatible graphics:
 
        VGA-compatible graphics:
 
-       <STRONG>o</STRONG>   COLOR_YELLOW is actually brown.  To get  yellow,  use  COLOR_YELLOW
+       <STRONG>o</STRONG>   COLOR_YELLOW  is  actually  brown.  To get yellow, use COLOR_YELLOW
            combined with the <STRONG>A_BOLD</STRONG> attribute.
 
            combined with the <STRONG>A_BOLD</STRONG> attribute.
 
-       <STRONG>o</STRONG>   The  A_BLINK  attribute should in theory cause the background to go
+       <STRONG>o</STRONG>   The A_BLINK attribute should in theory cause the background  to  go
            bright.  This often fails to work, and even some cards for which it
            bright.  This often fails to work, and even some cards for which it
-           mostly  works  (such  as the Paradise and compatibles) do the wrong
-           thing when you try to set a bright "yellow" background (you  get  a
+           mostly works (such as the Paradise and compatibles)  do  the  wrong
+           thing  when  you try to set a bright "yellow" background (you get a
            blinking yellow foreground instead).
 
        <STRONG>o</STRONG>   Color RGB values are not settable.
 
 
            blinking yellow foreground instead).
 
        <STRONG>o</STRONG>   Color RGB values are not settable.
 
 
-</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
-       SVr3.2 introduced color support to curses in 1987.
-
-       SVr4  made  internal  changes,  e.g.,  moving the storage for the color
-       state  from  <STRONG>SP</STRONG>  (the  <STRONG>SCREEN</STRONG>  structure)  to  <STRONG>cur_term</STRONG>  (the  <STRONG>TERMINAL</STRONG>
-       structure), but provided the same set of library functions.
-
-       SVr4  curses  limits  the  number of color pairs to 64, reserving color
-       pair zero (0) as the terminal's initial uncolored  state.   This  limit
-       arises  because  the color pair information is a bitfield in the <STRONG>chtype</STRONG>
-       data type (denoted by <STRONG>A_COLOR</STRONG>).
-
-       Other implementations of curses had different limits:
-
-       <STRONG>o</STRONG>   PCCurses (1987-1990) provided for only eight (8) colors.
-
-       <STRONG>o</STRONG>   PDCurses  (1992-present)  inherited  the  8-color  limitation  from
-           PCCurses, but changed this to 256 in version 2.5 (2001), along with
-           changing <STRONG>chtype</STRONG> from 16-bits to 32-bits.
-
-       <STRONG>o</STRONG>   X/Open Curses (1992-present) added a new structure <STRONG>cchar_t</STRONG> to store
-           the character, attributes and color-pair values, allowing increased
-           range of color-pairs.  Both color-pairs  and  color-values  used  a
-           signed <STRONG>short</STRONG>, limiting values to 15 bits.
-
-       <STRONG>o</STRONG>   ncurses  (1992-present)  uses  eight  bits  for  <STRONG>A_COLOR</STRONG>  in <STRONG>chtype</STRONG>
-           values.
-
-           Version 5.3 provided a wide-character interface  (2002),  but  left
-           color-pairs as part of the attributes-field.
-
-           Since version 6 (2015), ncurses uses a separate <STRONG>int</STRONG> for color-pairs
-           in the <STRONG>cchar_t</STRONG> values.  When those color-pair values fit in 8 bits,
-           ncurses  allows  color-pairs  to  be  manipulated via the functions
-           using <STRONG>chtype</STRONG> values.
-
-       <STRONG>o</STRONG>   NetBSD curses used  6  bits  from  2000  (when  colors  were  first
-           supported)  until  2004.   At  that point, NetBSD changed to use 10
-           bits.  As of 2021, that size is  unchanged.   Like  ncurses  before
-           version  6,  the  NetBSD  color-pair  information  is stored in the
-           attributes field of <STRONG>cchar_t</STRONG>, limiting the number of color-pairs  by
-           the size of the bitfield.
+</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
+       The functions marked as extensions were designed for  <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>,  and
+       are  not  found  in  SVr4  <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous
+       curses implementation.
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+       Applications employing <EM>ncurses</EM> extensions should condition their use on
+       the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
 
 
-</PRE><H3><a name="h3-Extensions">Extensions</a></H3><PRE>
-       The  functions  marked as extensions were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and
-       are not found in SVr4 curses, 4.4BSD  curses,  or  any  other  previous
-       version of curses.
-
-
-</PRE><H3><a name="h3-Standards">Standards</a></H3><PRE>
-       This  implementation satisfies XSI Curses's minimum maximums for <STRONG>COLORS</STRONG>
-       and <STRONG>COLOR_PAIRS</STRONG>.
+       This  implementation  satisfies  X/Open  Curses's  minimum maximums for
+       <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG>.
 
        The  <STRONG>init_pair</STRONG>  routine  accepts  negative  values  of  foreground  and
        background  color  to support the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> extension, but
 
        The  <STRONG>init_pair</STRONG>  routine  accepts  negative  values  of  foreground  and
        background  color  to support the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> extension, but
        <STRONG>short</STRONG>  parameters, allowing applications to use larger color- and pair-
        numbers.
 
        <STRONG>short</STRONG>  parameters, allowing applications to use larger color- and pair-
        numbers.
 
-       The <STRONG>reset_color_pairs</STRONG> function is an extension of ncurses.
+       The <STRONG>reset_color_pairs</STRONG> function is an extension of <EM>ncurses</EM>.
+
+
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+       SVr3.2 introduced color support to curses in 1987.
+
+       SVr4 made internal changes, e.g., moving  the  storage  for  the  color
+       state  from  <STRONG>SP</STRONG>  (the  <EM>SCREEN</EM>  structure)  to  <STRONG>cur_term</STRONG>  (the  <EM>TERMINAL</EM>
+       structure), but provided the same set of library functions.
+
+       SVr4 curses limits the number of color pairs  to  64,  reserving  color
+       pair  zero  (0)  as the terminal's initial uncolored state.  This limit
+       arises because the color pair information is a bitfield in  the  <STRONG>chtype</STRONG>
+       data type (denoted by <STRONG>A_COLOR</STRONG>).
+
+       Other implementations of curses had different limits:
+
+       <STRONG>o</STRONG>   PCCurses (1987-1990) provided for only eight (8) colors.
+
+       <STRONG>o</STRONG>   PDCurses  (1992-present)  inherited  the  8-color  limitation  from
+           PCCurses, but changed this to 256 in version 2.5 (2001), along with
+           changing <STRONG>chtype</STRONG> from 16-bits to 32-bits.
+
+       <STRONG>o</STRONG>   X/Open Curses (1992-present) added a new structure <STRONG>cchar_t</STRONG> to store
+           the character, attributes and color pair values, allowing increased
+           range  of  color  pairs.   Both color pairs and color-values used a
+           signed <STRONG>short</STRONG>, limiting values to 15 bits.
+
+       <STRONG>o</STRONG>   <EM>ncurses</EM> (1992-present)  uses  eight  bits  for  <STRONG>A_COLOR</STRONG>  in  <STRONG>chtype</STRONG>
+           values.
+
+           Version  5.3  provided  a wide-character interface (2002), but left
+           color pairs as part of the attributes-field.
+
+           Since version 6 (2015), ncurses uses a separate <STRONG>int</STRONG> for color pairs
+           in the <STRONG>cchar_t</STRONG> values.  When those color pair values fit in 8 bits,
+           ncurses allows color pairs to  be  manipulated  via  the  functions
+           using <STRONG>chtype</STRONG> values.
+
+       <STRONG>o</STRONG>   NetBSD  curses  used  6  bits  from  2000  (when  colors were first
+           supported) until 2004.  At that point, NetBSD  changed  to  use  10
+           bits.   As  of  2021,  that size is unchanged.  Like <EM>ncurses</EM> before
+           version 6, the NetBSD color  pair  information  is  stored  in  the
+           attributes  field of <STRONG>cchar_t</STRONG>, limiting the number of color pairs by
+           the size of the bitfield.
 
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,   <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,   <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,    <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
+       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,   <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,   <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,    <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
        <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
 
 
 
        <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
 
 
 
-ncurses 6.4                       2023-10-21                    <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
+ncurses 6.5                       2024-04-20                    <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 </PRE>
 <div class="nav">
 <ul>
 </PRE>
 <div class="nav">
 <ul>
@@ -534,7 +548,7 @@ ncurses 6.4                       2023-10-21                    <STRONG><A HREF=
 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 <ul>
 <li><a href="#h3-Overview">Overview</a></li>
 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 <ul>
 <li><a href="#h3-Overview">Overview</a></li>
-<li><a href="#h3-Color-Rendering">Color Rendering</a></li>
+<li><a href="#h3-Rendering">Rendering</a></li>
 </ul>
 </li>
 <li><a href="#h2-CONSTANTS">CONSTANTS</a></li>
 </ul>
 </li>
 <li><a href="#h2-CONSTANTS">CONSTANTS</a></li>
@@ -558,19 +572,15 @@ ncurses 6.4                       2023-10-21                    <STRONG><A HREF=
 <li><a href="#h3-pair_content">pair_content</a></li>
 <li><a href="#h3-extended_pair_content">extended_pair_content</a></li>
 <li><a href="#h3-reset_color_pairs">reset_color_pairs</a></li>
 <li><a href="#h3-pair_content">pair_content</a></li>
 <li><a href="#h3-extended_pair_content">extended_pair_content</a></li>
 <li><a href="#h3-reset_color_pairs">reset_color_pairs</a></li>
-<li><a href="#h3-PAIR_NUMBER">PAIR_NUMBER</a></li>
 <li><a href="#h3-COLOR_PAIR">COLOR_PAIR</a></li>
 <li><a href="#h3-COLOR_PAIR">COLOR_PAIR</a></li>
+<li><a href="#h3-PAIR_NUMBER">PAIR_NUMBER</a></li>
 </ul>
 </li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 <li><a href="#h2-NOTES">NOTES</a></li>
 </ul>
 </li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 <li><a href="#h2-NOTES">NOTES</a></li>
+<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 <li><a href="#h2-HISTORY">HISTORY</a></li>
 <li><a href="#h2-HISTORY">HISTORY</a></li>
-<li><a href="#h2-PORTABILITY">PORTABILITY</a>
-<ul>
-<li><a href="#h3-Extensions">Extensions</a></li>
-<li><a href="#h3-Standards">Standards</a></li>
-</ul>
-</li>
 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 </ul>
 </div>
 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 </ul>
 </div>