Documented Tk_PreserveColormap. [Bug 220809]

1 files changed, 14 insertions, 8 deletions

diff --git a/doc/GetClrmap.3 b/doc/GetClrmap.3
index 88f562c..cfb84d9 100644
--- a/doc/GetClrmap.3
+++ b/doc/GetClrmap.3
@@ -5,13 +5,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetClrmap.3,v 1.6 2007/12/13 15:23:43 dgp Exp $
+'\" RCS: @(#) $Id: GetClrmap.3,v 1.7 2008/03/19 15:34:41 dkf Exp $
 '\" 
 .so man.macros
 .TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetColormap, Tk_FreeColormap \- allocate and free colormaps
+Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
@@ -19,6 +19,8 @@ Tk_GetColormap, Tk_FreeColormap \- allocate and free colormaps
 Colormap
 \fBTk_GetColormap(\fIinterp, tkwin, string\fB)\fR
 .sp
+\fBTk_PreserveColormap(\fIdisplay, colormap\fB)\fR
+.sp
 \fBTk_FreeColormap(\fIdisplay, colormap\fB)\fR
 .SH ARGUMENTS
 .AS "Colormap" colormap
@@ -32,10 +34,9 @@ with the same screen and visual as \fItkwin\fR.
 .AP Display *display in
 Display for which \fIcolormap\fR was allocated.
 .AP Colormap colormap in
-Colormap to free;  must have been returned by a previous
+Colormap to free or preserve;  must have been returned by a previous
 call to \fBTk_GetColormap\fR or \fBTk_GetVisual\fR.
 .BE
-
 .SH DESCRIPTION
 .PP
 These procedures are used to manage colormaps.
@@ -47,13 +48,19 @@ window is returned.
 If \fIstring\fR does not make sense, or if it refers to a window on
 a different screen from \fItkwin\fR or with
 a different visual than \fItkwin\fR, then \fBTk_GetColormap\fR returns
-\fBNone\fR and leaves an error message in \fIinterp->result\fR.
+\fBNone\fR and leaves an error message in \fIinterp\fR's result.
+.PP
+\fBTk_PreserveColormap\fR increases the internal reference count for a
+colormap previously returned by \fBTk_GetColormap\fR, which allows the
+colormap to be stored in several locations without knowing which order
+they will be released.
 .PP
 \fBTk_FreeColormap\fR should be called when a colormap returned by
 \fBTk_GetColormap\fR is no longer needed.
 Tk maintains a reference count for each colormap returned by
 \fBTk_GetColormap\fR, so there should eventually be one call to
-\fBTk_FreeColormap\fR for each call to \fBTk_GetColormap\fR.
+\fBTk_FreeColormap\fR for each call to \fBTk_GetColormap\fR and each
+call to \fBTk_PreserveColormap\fR.
 When a colormap's reference count becomes zero, Tk releases the
 X colormap.
 .PP
@@ -68,6 +75,5 @@ If \fBTk_GetColormap\fR is called with a \fIstring\fR value of
 be returned by \fBTk_GetVisual\fR;  however, it can be used in other
 windows by calling \fBTk_GetColormap\fR with the original window's
 name as \fIstring\fR.
-
 .SH KEYWORDS
-colormap
+colormap, visual