X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_color.3x;h=801ac9fa6b0029f3e8a09939a5ed554a2729880c;hp=7ca76907b59f0781c619bfe331a392d69a353f24;hb=41677b308e138027b7e435f741ee7fe5651237b0;hpb=55ccd2b959766810cf7db8d1c4462f338ce0afc8;ds=sidebyside diff --git a/man/curs_color.3x b/man/curs_color.3x index 7ca76907..801ac9fa 100644 --- a/man/curs_color.3x +++ b/man/curs_color.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2004,2005 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2005,2009 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 * @@ -26,7 +26,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_color.3x,v 1.27 2005/05/15 16:55:36 tom Exp $ +.\" $Id: curs_color.3x,v 1.29 2009/01/24 23:10:02 tom Exp $ .TH curs_color 3X "" .na .hy 0 @@ -68,7 +68,7 @@ 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\fR, can be used as a new video attribute. -.SP +.PP 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, @@ -88,7 +88,7 @@ and white), and two global variables, \fBCOLORS\fR and 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. -.SP +.PP 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. @@ -96,7 +96,10 @@ For portable applications: .TP 5 - The value of the first argument -must be between \fB1\fR and \fBCOLOR_PAIRS-1\fR. +must be between \fB1\fR and \fBCOLOR_PAIRS-1\fR, +except that if default colors are used (see \fBuse_default_colors\fP) +the upper limit is adjusted to allow for extra pairs which use +a default color in foreground and/or background. .TP 5 - The value of the second and @@ -108,12 +111,12 @@ It cannot be modified by the application. If the color-pair was previously initialized, the screen is refreshed and all occurrences of that color-pair are changed to the new definition. -.SP +.PP As an extension, ncurses allows you to set color pair 0 via the \fBassume_default_colors\fR routine, or to specify the use of default colors (color number \fB-1\fR) if you first invoke the \fBuse_default_colors\fR routine. -.SP +.PP 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 @@ -122,18 +125,18 @@ argument must be between \fB0\fR and \fBCOLORS\fR. (See the section 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. -.SP +.PP 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. -.SP +.PP 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. -.SP +.PP 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 @@ -142,7 +145,7 @@ 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). -.SP +.PP 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 @@ -153,7 +156,7 @@ to by the second and third arguments are between 0 and \fBCOLORS\fR. In \fB\fR the following macros are defined. These are the default colors. \fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default background color for all terminals. -.SP +.PP .nf \fBCOLOR_BLACK\fR \fBCOLOR_RED\fR @@ -167,7 +170,7 @@ background color for all terminals. .SH RETURN VALUE The routines \fBcan_change_color()\fR and \fBhas_colors()\fR return \fBTRUE\fR or \fBFALSE\fR. -.SP +.PP All other routines return the integer \fBERR\fR upon failure and an \fBOK\fR (SVr4 specifies only "an integer value other than \fBERR\fR") upon successful completion. @@ -199,12 +202,12 @@ color palette, color pairs table, and associated COLORS and COLOR_PAIRS counts for each screen; the \fBstart_color\fR 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. -.SP +.PP Note that 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 \fBcurs_bkgd\fR(3X). -.SP +.PP Several caveats apply on 386 and 486 machines with VGA-compatible graphics: .TP 5 -