+<!--
+ ****************************************************************************
+ * Copyright 2018-2019,2020 Thomas E. Dickey *
+ * Copyright 2000-2011,2016 Free Software Foundation, Inc. *
+ * *
+ * Permission is hereby granted, free of charge, to any person obtaining a *
+ * copy of this software and associated documentation files (the *
+ * "Software"), to deal in the Software without restriction, including *
+ * without limitation the rights to use, copy, modify, merge, publish, *
+ * distribute, distribute with modifications, sublicense, and/or sell *
+ * copies of the Software, and to permit persons to whom the Software is *
+ * furnished to do so, subject to the following conditions: *
+ * *
+ * The above copyright notice and this permission notice shall be included *
+ * in all copies or substantial portions of the Software. *
+ * *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+ * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+ * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+ * *
+ * Except as contained in this notice, the name(s) of the above copyright *
+ * holders shall not be used in advertising or otherwise to promote the *
+ * sale, use or other dealings in this Software without prior written *
+ * authorization. *
+ ****************************************************************************
+ * Author: Thomas E. Dickey 1997,1999,2000,2005
+ * @Id: default_colors.3x,v 1.31 2020/12/19 21:38:37 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">
+<TITLE>default_colors 3X</TITLE>
+<link rel="author" href="mailto:bug-ncurses@gnu.org">
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+</HEAD>
<BODY>
+<H1 class="no-header">default_colors 3X</H1>
<PRE>
-<!-- Manpage converted by man2html 3.0.1 -->
+<B><A HREF="default_colors.3X.html">default_colors(3X)</A></B> <B><A HREF="default_colors.3X.html">default_colors(3X)</A></B>
-</PRE>
-<H2>NAME</H2><PRE>
- <B>default_colors</B>: <B>use_default_colors</B>, <B>assume_default_colors</B>
- - use terminal's default colors
-</PRE>
-<H2>SYNOPSIS</H2><PRE>
- <B>#include</B> <B><curses.h></B>
- <B>int</B> <B>use_default_colors(void);</B>
- <B>int</B> <B>assume_default_colors(int</B> <B>fg,</B> <B>int</B> <B>bg);</B>
+</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
+ <B>use_default_colors</B>, <B>assume_default_colors</B> - use terminal's default
+ colors
-</PRE>
-<H2>DESCRIPTION</H2><PRE>
- The <I>use</I><B>_</B><I>default</I><B>_</B><I>colors()</I> and <I>assume</I><B>_</B><I>default</I><B>_</B><I>colors()</I> func-
- tions are extensions to the curses library. They are used
- with terminals that support ISO 6429 color, or equivalent.
- These terminals allow the application to reset color to an
- unspecified default value (e.g., with SGR 39 or SGR 49).
-
- Applications that paint a colored background over the
- whole screen do not take advantage of SGR 39 and SGR 49.
- Some applications are designed to work with the default
- background, using colors only for text. For example,
- there are several implementations of the <B>ls</B> program which
- use colors to denote different file types or permissions.
- These "color ls" programs do not necessarily modify the
- background color, typically using only the <I>setaf</I> terminfo
- capability to set the foreground color. Full-screen
- applications that use default colors can achieve similar
- visual effects.
-
- The first function, <I>use</I><B>_</B><I>default</I><B>_</B><I>colors()</I> tells the curses
- library to assign terminal default foreground/background
- colors to color number -1. So init_pair(x,COLOR_RED,-1)
- will initialize pair x as red on default background and
- init_pair(x,-1,COLOR_BLUE) will initialize pair x as
- default foreground on blue.
-
- The other, <I>assume</I><B>_</B><I>default</I><B>_</B><I>colors()</I> is a refinement which
- tells which colors to paint for color pair 0. This func-
- tion recognizes a special color number -1, which denotes
- the default terminal color.
+</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
+ <B>#include</B> <B><curses.h></B>
+
+ <B>int</B> <B>use_default_colors(void);</B>
+ <B>int</B> <B>assume_default_colors(int</B> <I>fg</I><B>,</B> <B>int</B> <I>bg</I><B>);</B>
+
+
+</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+ The <B>use_default_colors</B> and <B>assume_default_colors</B> functions are
+ extensions to the curses library. They are used with terminals that
+ support ISO 6429 color, or equivalent. These terminals allow the
+ application to reset color to an unspecified default value (e.g., with
+ SGR 39 or SGR 49).
+
+ Applications that paint a colored background over the whole screen do
+ not take advantage of SGR 39 and SGR 49. Some applications are
+ designed to work with the default background, using colors only for
+ text. For example, there are several implementations of the <B>ls</B> program
+ which use colors to denote different file types or permissions. These
+ "color ls" programs do not necessarily modify the background color,
+ typically using only the <B>setaf</B> terminfo capability to set the
+ foreground color. Full-screen applications that use default colors can
+ achieve similar visual effects.
+
+ The first function, <B>use_default_colors</B> tells the curses library to
+ assign terminal default foreground/background colors to color number
+ -1. So init_pair(x,COLOR_RED,-1) will initialize pair x as red on
+ default background and init_pair(x,-1,COLOR_BLUE) will initialize pair
+ x as default foreground on blue.
+
+ The other, <B>assume_default_colors</B> is a refinement which tells which
+ colors to paint for color pair 0. This function recognizes a special
+ color number -1, which denotes the default terminal color.
The following are equivalent:
<I>use</I><B>_</B><I>default</I><B>_</B><I>colors();</I>
<I>assume</I><B>_</B><I>default</I><B>_</B><I>colors(-1,-1);</I>
- These are ncurses extensions. For other curses implemen-
- tations, color number -1 does not mean anything, just as
- for ncurses before a successful call of <I>use</I><B>_</B><I>default</I><B>_</B><I>col-</I>
- <I>ors()</I> or <I>assume</I><B>_</B><I>default</I><B>_</B><I>colors()</I>.
-
- Other curses implementations do not allow an application
- to modify color pair 0. They assume that the background
- is COLOR_BLACK, but do not ensure that the color pair 0 is
- painted to match the assumption. If your application does
- not use either <I>use</I><B>_</B><I>default</I><B>_</B><I>colors()</I> or <I>assume</I><B>_</B><I>default</I><B>_</B><I>col-</I>
- <I>ors()</I> ncurses will paint a white foreground (text) with
- black background for color pair 0.
-
-
-</PRE>
-<H2>RETURN VALUE</H2><PRE>
- These functions return the integer <B>ERR</B> upon failure and <B>OK</B>
- on success. They will fail if either the terminal does
- not support the <I>orig</I><B>_</B><I>pair</I> or <I>orig</I><B>_</B><I>colors</I> capability. If
- the <I>initialize</I><B>_</B><I>pair</I> capability is found, this causes an
- error as well.
-
-
-</PRE>
-<H2>NOTES</H2><PRE>
- Associated with this extension, the <B><A HREF="init_pair.3x.html">init_pair(3x)</A></B> function
- accepts negative arguments to specify default foreground
- or background colors.
-
-
-</PRE>
-<H2>PORTABILITY</H2><PRE>
- These routines are specific to ncurses. They were not
- supported on Version 7, BSD or System V implementations.
- It is recommended that any code depending on them be con-
- ditioned using NCURSES_VERSION.
-
-
-</PRE>
-<H2>SEE ALSO</H2><PRE>
- <B><A HREF="curs_color.3x.html">curs_color(3x)</A></B>, <B><A HREF="ded.1.html">ded(1)</A></B>.
-
-
-</PRE>
-<H2>AUTHOR</H2><PRE>
- Thomas Dickey (from an analysis of the requirements for
- color xterm for XFree86 3.1.2C, February 1996).
-
-
-
-
-
-
-
-
-
-
+ These are ncurses extensions. For other curses implementations, color
+ number -1 does not mean anything, just as for ncurses before a
+ successful call of <B>use_default_colors</B> or <B>assume_default_colors</B>.
+ Other curses implementations do not allow an application to modify
+ color pair 0. They assume that the background is COLOR_BLACK, but do
+ not ensure that the color pair 0 is painted to match the assumption.
+ If your application does not use either <B>use_default_colors</B> or
+ <B>assume_default_colors</B> ncurses will paint a white foreground (text) with
+ black background for color pair 0.
+</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
+ These functions return the integer <B>ERR</B> upon failure and <B>OK</B> on success.
+ They will fail if either the terminal does not support the <B>orig_pair</B> or
+ <B>orig_colors</B> capability. If the <B>initialize_pair</B> capability is not
+ found, this causes an error as well.
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+ Associated with this extension, the <B>init_pair</B> function accepts negative
+ arguments to specify default foreground or background colors.
+ The <B>use_default_colors</B> function was added to support <I>ded</I>. This is a
+ full-screen application which uses curses to manage only part of the
+ screen. The bottom portion of the screen, which is of adjustable size,
+ is left uncolored to display the results from shell commands. The top
+ portion of the screen colors filenames using a scheme like the "color
+ ls" programs. Attempting to manage the background color of the screen
+ for this application would give unsatisfactory results for a variety of
+ reasons. This extension was devised after noting that color xterm (and
+ similar programs) provides a background color which does not
+ necessarily correspond to any of the ANSI colors. While a special
+ terminfo entry could be constructed using nine colors, there was no
+ mechanism provided within curses to account for the related <B>orig_pair</B>
+ and <B>back_color_erase</B> capabilities.
+ The <B>assume_default_colors</B> function was added to solve a different
+ problem: support for applications which would use environment variables
+ and other configuration to bypass curses' notion of the terminal's
+ default colors, setting specific values.
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+ These routines are specific to ncurses. They were not supported on
+ Version 7, BSD or System V implementations. It is recommended that any
+ code depending on them be conditioned using NCURSES_VERSION.
+</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
+ <B>ded(1)</B>, <B><A HREF="curs_color.3X.html">curs_color(3X)</A></B>.
+</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
+ Thomas Dickey (from an analysis of the requirements for color xterm for
+ XFree86 3.1.2C, February 1996).
+ <B><A HREF="default_colors.3X.html">default_colors(3X)</A></B>
</PRE>
-<HR>
-<ADDRESS>
-Man(1) output converted with
-<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
-</ADDRESS>
+<div class="nav">
+<ul>
+<li><a href="#h2-NAME">NAME</a></li>
+<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
+<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
+<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
+<li><a href="#h2-NOTES">NOTES</a></li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
+<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
+<li><a href="#h2-AUTHOR">AUTHOR</a></li>
+</ul>
+</div>
</BODY>
</HTML>
projects / ncurses.git / blobdiff