Moved from ports with several enhancements

1 files changed, 138 insertions, 0 deletions

diff --git a/lib/libncurses/curs_color.3 b/lib/libncurses/curs_color.3
new file mode 100644
index 0000000..56f9379
--- /dev/null
+++ b/lib/libncurses/curs_color.3
@@ -0,0 +1,138 @@
+.TH curs_color 3X ""
+.SH NAME
+\fBcurs_color\fR: \fBstart_color\fR, \fBinit_pair\fR,
+\fBinit_color\fR, \fBhas_colors\fR, \fBcan_change_color\fR,
+\fBcolor_content\fR, \fBpair_content\fR - \fBncurses\fR color
+manipulation routines
+.SH SYNOPSIS
+\fB# include <ncurses.h>\fR
+.br
+\fBint start_color(void);\fR
+.br
+\fBint init_pair(short pair, short f, short b);\fR
+.br
+\fBint init_color(short color, short r, short g, short b);\fR
+.br
+\fBbool has_colors(void);\fR
+.br
+\fBbool can_change_color(void);\fR
+.br
+\fBint color_content(short color, short *r, short *g, short *b);\fR
+.br
+\fBint pair_content(short pair, short *f, short *b);\fR
+.br
+.SH DESCRIPTION
+.SS Overview
+\fBncurses\fR support color attributes on terminals with that capability.  To
+use these routines \fBstart_color\fR must be called, usually right after
+\fBinitscr\fR.  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 \fBinit_pair\fR.  After it
+has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR), a macro defined in
+\fB<ncurses.h>\fR, can be used as a new video attribute.
+
+If a terminal is capable of redefining colors, the programmer can use the
+routine \fBinit_color\fR to change the definition of a color.  The routines
+\fBhas_colors\fR and \fBcan_change_color\fR return \fBTRUE\fR or \fBFALSE\fR,
+depending on whether the terminal has color capabilities and whether the
+programmer can change the colors.  The routine \fBcolor_content\fR allows a
+programmer to extract the amounts of red, green, and blue components in an
+initialized color.  The routine \fBpair_content\fR allows a programmer to find
+out how a given color-pair is currently defined.
+.SS Routine Descriptions
+The \fBstart_color\fR routine requires no arguments.  It must be
+called if the programmer wants to use colors, and before any other
+color manipulation routine is called.  It is good practice to call
+this routine right after \fBinitscr\fR.  \fBstart_color\fR initializes
+eight basic colors (black, red, green, yellow, blue, magenta, cyan,
+and white), and two global variables, \fBCOLORS\fR and
+\fBCOLOR_PAIRS\fR (respectively defining the maximum number of colors
+and color-pairs the terminal can support).  It also restores the
+colors on the terminal to the values they had when the terminal was
+just turned on.
+
+The \fBinit_pair\fR 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.  The value of the first argument
+must be between \fB1\fR and \fBCOLOR_PAIRS-1\fR.  The value of the second and
+third arguments must be between 0 and \fBCOLORS\fR (the 0 color pair is wired
+to white on black and cannot be changed).  If the color-pair was previously
+initialized, the screen is refreshed and all occurrences of that color-pair is
+changed to the new definition.
+
+The \fBinit_color\fR routine changes the definition of a color.  It takes four
+arguments: the number of the color to be changed followed by three RGB values
+(for the amounts of red, green, and blue components).  The value of the first
+argument must be between \fB0\fR and \fBCOLORS\fR.  (See the section
+\fBColors\fR for the default color index.)  Each of the last three arguments
+must be a value between 0 and 1000.  When \fBinit_color\fR is used, all
+occurrences of that color on the screen immediately change to the new
+definition.
+
+The \fBhas_colors\fR routine requires no arguments.  It returns \fBTRUE\fR if
+the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR.  This
+routine facilitates writing terminal-independent programs.  For example, a
+programmer can use it to decide whether to use color or some other video
+attribute.
+
+The \fBcan_change_color\fR routine requires no arguments.  It returns
+\fBTRUE\fR if the terminal supports colors and can change their definitions;
+other, it returns \fBFALSE\fR.  This routine facilitates writing
+terminal-independent programs.
+
+The \fBcolor_content\fR routine gives programmers a way to find the intensity
+of the red, green, and blue (RGB) components in a color.  It requires four
+arguments: the color number, and three addresses of \fBshort\fRs for storing
+the information about the amounts of red, green, and blue components in the
+given color.  The value of the first argument must be between 0 and
+\fBCOLORS\fR.  The values that are stored at the addresses pointed to by the
+last three arguments are between 0 (no component) and 1000 (maximum amount of
+component).
+
+The \fBpair_content\fR routine allows programmers to find out what colors a
+given color-pair consists of.  It requires three arguments: the color-pair
+number, and two addresses of \fBshort\fRs for storing the foreground and the
+background color numbers.  The value of the first argument must be between 1
+and \fBCOLOR_PAIRS-1\fR.  The values that are stored at the addresses pointed
+to by the second and third arguments are between 0 and \fBCOLORS\fR.
+.SS Colors
+In \fB<ncurses.h>\fR the following macros are defined.  These are the default
+colors.  \fBncurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
+background color for all terminals.
+
+.nf
+      \fBCOLOR_BLACK\fR
+      \fBCOLOR_RED\fR
+      \fBCOLOR_GREEN\fR
+      \fBCOLOR_YELLOW\fR
+      \fBCOLOR_BLUE\fR
+      \fBCOLOR_MAGENTA\fR
+      \fBCOLOR_CYAN\fR
+      \fBCOLOR_WHITE\fR
+.fi
+.SH RETURN VALUE
+All routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
+upon successful completion.
+.SH BUGS
+Several caveats apply onn 386 and 486 machines with VGA-compatible graphics:
+
+COLOR_YELLOW is actually brown.  To get yellow, use COLOR_YELLOW combined with
+the \fBA_BOLD\fR attribute.
+
+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 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).
+
+Color RGB values are not settable.
+.SH CAPABILITIES
+\fBsetf\fR, \fBsetb\fR, \fBsetaf\fR, \fBsetab\fR.  The ncurses library uses
+the second pair by preference, falling back to the first.
+.SH SEE ALSO
+\fBncurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_attr\fR(3X)
+.\"#
+.\"# The following sets edit modes for GNU EMACS
+.\"# Local Variables:
+.\"# mode:nroff
+.\"# fill-column:79