ncurses 5.7 - patch 20090906

[ncurses.git] / man / default_colors.3x

diff --git a/man/default_colors.3x b/man/default_colors.3x
index 9d6d97c9e803e3a806758e256be38f20f30afa95..32518ba9d9cf1124a8a20f170400fd53a5754f65 100644 (file)
--- a/man/default_colors.3x
+++ b/man/default_colors.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright (c) 1998,1999,2000 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2005,2006 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            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *


@@ -26,22 +26,19 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" Author: Thomas E. Dickey <dickey@clark.net> 1997,1999,2000
+.\" Author: Thomas E. Dickey 1997,1999,2000,2005

 .\"
 .\"

-.\" $Id: default_colors.3x,v 1.13 2000/07/15 22:06:50 tom Exp $
+.\" $Id: default_colors.3x,v 1.20 2006/12/24 15:02:53 tom Exp $

 .TH default_colors 3X ""
 .SH NAME
 .TH default_colors 3X ""
 .SH NAME

-\fBdefault_colors\fR:

 \fBuse_default_colors\fR,
 \fBassume_default_colors\fR \- use terminal's default colors
 \fBuse_default_colors\fR,
 \fBassume_default_colors\fR \- use terminal's default colors

-..

 .SH SYNOPSIS
 \fB#include <curses.h>\fP
 .SH SYNOPSIS
 \fB#include <curses.h>\fP

-
+.sp

 \fBint use_default_colors(void);\fP
 .br
 \fBint assume_default_colors(int fg, int bg);\fP
 \fBint use_default_colors(void);\fP
 .br
 \fBint assume_default_colors(int fg, int bg);\fP

-..

 .SH DESCRIPTION
 The
 .I use_default_colors()
 .SH DESCRIPTION
 The
 .I use_default_colors()


@@ -100,28 +97,42 @@ or
 .I assume_default_colors()
 ncurses will paint a white foreground (text) with black background
 for color pair 0.
 .I assume_default_colors()
 ncurses will paint a white foreground (text) with black background
 for color pair 0.

-..

 .SH RETURN VALUE
 These functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
 They will fail if either the terminal does not support
 the \fIorig_pair\fP or \fIorig_colors\fP capability.
 If the \fIinitialize_pair\fP capability is found, this causes an
 error as well.
 .SH RETURN VALUE
 These functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
 They will fail if either the terminal does not support
 the \fIorig_pair\fP or \fIorig_colors\fP capability.
 If the \fIinitialize_pair\fP capability is found, this causes an
 error as well.

-..

 .SH NOTES
 .SH NOTES

-Associated with this extension, the \fBinit_pair\fR(3X) function accepts
-negative arguments to specify default foreground or background
-colors.
-..
+Associated with this extension, the \fBinit_pair\fR function accepts
+negative arguments to specify default foreground or background colors.
+.PP
+The \fIuse_default_colors()\fP function was added to support \fIded\fP.
+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
+\fIorig_pair\fP and \fIback_color_erase\fP capabilities.
+.PP
+The \fIassume_default_colors()\fP 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.

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

-..

 .SH SEE ALSO
 \fBcurs_color\fR(3X),
 \fBded\fP(1).
 .SH SEE ALSO
 \fBcurs_color\fR(3X),
 \fBded\fP(1).

-..

 .SH AUTHOR
 Thomas Dickey (from an analysis of the requirements for color xterm
 for XFree86 3.1.2C, February 1996).
 .SH AUTHOR
 Thomas Dickey (from an analysis of the requirements for color xterm
 for XFree86 3.1.2C, February 1996).