* Merged 8.1 branch into the main trunk

1 files changed, 99 insertions, 55 deletions

diff --git a/doc/GetColor.3 b/doc/GetColor.3
index 4b551f2..d5abc78 100644
--- a/doc/GetColor.3
+++ b/doc/GetColor.3
@@ -1,32 +1,44 @@
 '\"
-'\" Copyright (c) 1990, 1991 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1990-1991 The Regents of the University of California.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: GetColor.3,v 1.2 1998/09/14 18:22:48 stanton Exp $
+'\" RCS: @(#) $Id: GetColor.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetColor 3 4.0 Tk "Tk Library Procedures"
+.TH Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetColor, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColor \- maintain database of colors
+Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor \- maintain database of colors
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
+.VS 8.1
 .sp
 XColor *
-\fBTk_GetColor\fR(\fIinterp, tkwin, nameId\fB)\fR
+\fBTk_AllocColorFromObj(\fIinterp, tkwin, objPtr\fB)\fR
 .sp
 XColor *
-\fBTk_GetColorByValue\fR(\fItkwin, prefPtr\fB)\fR
+\fBTk_GetColor(\fIinterp, tkwin, name\fB)\fR
+.sp
+XColor *
+\fBTk_GetColorFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
+XColor *
+\fBTk_GetColorByValue(\fItkwin, prefPtr\fB)\fR
 .sp
 char *
 \fBTk_NameOfColor(\fIcolorPtr\fB)\fR
 .sp
 GC
-\fBTk_GCForColor\fR(\fIcolorPtr, drawable\fR)
+\fBTk_GCForColor(\fIcolorPtr, drawable\fB)\fR
+.sp
+.VS 8.1
+\fBTk_FreeColorFromObj(\fItkwin, objPtr\fB)\fR
+.VE
 .sp
 \fBTk_FreeColor(\fIcolorPtr\fB)\fR
 .SH ARGUMENTS
@@ -35,27 +47,39 @@ GC
 Interpreter to use for error reporting.
 .AP Tk_Window tkwin in
 Token for window in which color will be used.
-.AP Tk_Uid nameId in
-Textual description of desired color.
+.VS 8.1 br
+.AP Tcl_Obj *objPtr in/out
+String value describes desired color; internal rep will be
+modified to cache pointer to corresponding (XColor *).
+.AP char *name in
+Same as \fIobjPtr\fR except description of color is passed as a string and
+resulting (XColor *) isn't cached.
+.VE
 .AP XColor *prefPtr in
 Indicates red, green, and blue intensities of desired
 color.
 .AP XColor *colorPtr in
 Pointer to X color information.  Must have been allocated by previous
-call to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR, except when passed
-to \fBTk_NameOfColor\fR.
+call to \fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR or
+\fBTk_GetColorByValue\fR, except when passed to \fBTk_NameOfColor\fR.
 .AP Drawable drawable in
 Drawable in which the result graphics context will be used.  Must have
 same screen and depth as the window for which the color was allocated.
 .BE
 
 .SH DESCRIPTION
+.VS 8.1
+.PP
+These procedures manage the colors being used by a Tk application.
+They allow colors to be shared whenever possible, so that colormap
+space is preserved, and they pick closest available colors when
+colormap space is exhausted.
 .PP
-The \fBTk_GetColor\fR and \fBTk_GetColorByValue\fR procedures
-locate pixel values that may be used to render particular
-colors in the window given by \fItkwin\fR.  In \fBTk_GetColor\fR
-the desired color is specified with a Tk_Uid (\fInameId\fR), which
-may have any of the following forms:
+Given a textual description of a color, \fBTk_AllocColorFromObj\fR
+locates a pixel value that may be used to render the color
+in a particular window.  The desired color is specified with an
+object whose string value must have one of the following forms:
+.VE
 .TP 20
 \fIcolorname\fR
 Any of the valid textual names for a color defined in the
@@ -76,38 +100,56 @@ When fewer than 16 bits are provided for each color, they represent
 the most significant bits of the color.  For example, #3a7 is the
 same as #3000a0007000.
 .PP
-In \fBTk_GetColorByValue\fR, the desired color is indicated with
-the \fIred\fR, \fIgreen\fR, and \fIblue\fR fields of the structure
-pointed to by \fIcolorPtr\fR.
-.PP
-If \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR is successful
-in allocating the desired color, then it returns a pointer to
+.VS 8.1
+\fBTk_AllocColorFromObj\fR returns a pointer to
 an XColor structure;  the structure indicates the exact intensities of
 the allocated color (which may differ slightly from those requested,
 depending on the limitations of the screen) and a pixel value
-that may be used to draw in the color.
-If the colormap for \fItkwin\fR is full, \fBTk_GetColor\fR
-and \fBTk_GetColorByValue\fR will use the closest existing color
-in the colormap.
-If \fBTk_GetColor\fR encounters an error while allocating
-the color (such as an unknown color name) then NULL is returned and
-an error message is stored in \fIinterp->result\fR;
-\fBTk_GetColorByValue\fR never returns an error.
+that may be used to draw with the color in \fItkwin\fR.
+If an error occurs in \fBTk_AllocColorFromObj\fR (such as an unknown
+color name) then NULL is returned and an error message is stored in
+\fIinterp\fR's result if \fIinterp\fR isn't NULL.
+If the colormap for \fItkwin\fR is full, \fBTk_AllocColorFromObj\fR
+will use the closest existing color in the colormap.
+\fBTk_AllocColorFromObj\fR caches information about
+the return value in \fIobjPtr\fR, which speeds up future calls to procedures
+such as \fBTk_AllocColorFromObj\fR and \fBTk_GetColorFromObj\fR.
+.PP
+\fBTk_GetColor\fR is identical to \fBTk_AllocColorFromObj\fR except
+that the description of the color is specified with a string instead
+of an object.  This prevents \fBTk_GetColor\fR from caching the
+return value, so \fBTk_GetColor\fR is less efficient than
+\fBTk_AllocColorFromObj\fR.
+.PP
+\fBTk_GetColorFromObj\fR returns the token for an existing color, given
+the window and description used to create the color.
+\fBTk_GetColorFromObj\fR doesn't actually create the color; the color
+must already have been created with a previous call to
+\fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetColorFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.VE
 .PP
-\fBTk_GetColor\fR and \fBTk_GetColorByValue\fR maintain a database
+\fBTk_GetColorByValue\fR is similar to \fBTk_GetColor\fR except that
+the desired color is indicated with the \fIred\fR, \fIgreen\fR, and
+\fIblue\fR fields of the structure pointed to by \fIcolorPtr\fR.
+.PP
+This package maintains a database
 of all the colors currently in use.
-If the same \fInameId\fR is requested multiple times from
-\fBTk_GetColor\fR (e.g. by different windows), or if the
+If the same color is requested multiple times from
+\fBTk_GetColor\fR or \fBTk_AllocColorFromObj\fR (e.g. by different
+windows), or if the 
 same intensities are requested multiple times from
 \fBTk_GetColorByValue\fR, then existing pixel values will
 be re-used.  Re-using an existing pixel avoids any interaction
-with the X server, which makes the allocation much more
-efficient.  For this reason, you should generally use
-\fBTk_GetColor\fR or \fBTk_GetColorByValue\fR
-instead of Xlib procedures like \fBXAllocColor\fR,
-\fBXAllocNamedColor\fR, or \fBXParseColor\fR.
+with the window server, which makes the allocation much more
+efficient.  These procedures also provide a portable interface that
+works across all platforms.  For this reason, you should generally use
+\fBTk_AllocColorFromObj\fR, \fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR
+instead of lower level procedures like \fBXAllocColor\fR.
 .PP
-Since different calls to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR
+Since different calls to this package
 may return the same shared
 pixel value, callers should never change the color of a pixel
 returned by the procedures.
@@ -116,15 +158,16 @@ If you need to change a color value dynamically, you should use
 .PP
 The procedure \fBTk_NameOfColor\fR is roughly the inverse of
 \fBTk_GetColor\fR.  If its \fIcolorPtr\fR argument was created
-by \fBTk_GetColor\fR, then the return value is the \fInameId\fR
-string that was passed to \fBTk_GetColor\fR to create the
+by \fBTk_AllocColorFromObj\fR or \fBTk_GetColor\fR then the return value
+is the string that was used to create the
 color.  If \fIcolorPtr\fR was created by a call to \fBTk_GetColorByValue\fR,
 or by any other mechanism, then the return value is a string
 that could be passed to \fBTk_GetColor\fR to return the same
 color.  Note:  the string returned by \fBTk_NameOfColor\fR is
-only guaranteed to persist until the next call to \fBTk_NameOfColor\fR.
+only guaranteed to persist until the next call to
+\fBTk_NameOfColor\fR.
 .PP
-\fBTk_GCForColor\fR returns a graphics context whose \fBForeground\fR
+\fBTk_GCForColor\fR returns a graphics context whose \fBforeground\fR
 field is the pixel allocated for \fIcolorPtr\fR and whose other fields
 all have default values.
 This provides an easy way to do basic drawing with a color.
@@ -132,15 +175,16 @@ The graphics context is cached with the color and will exist only as
 long as \fIcolorPtr\fR exists;  it is freed when the last reference
 to \fIcolorPtr\fR is freed by calling \fBTk_FreeColor\fR.
 .PP
-When a pixel value returned by \fBTk_GetColor\fR or
-\fBTk_GetColorByValue\fR is no longer
-needed, \fBTk_FreeColor\fR should be called to release the color.
-There should be exactly one call to \fBTk_FreeColor\fR for
-each call to \fBTk_GetColor\fR or \fBTk_GetColorByValue\fR.
-When a pixel value is no longer in
-use anywhere (i.e. it has been freed as many times as it has been gotten)
-\fBTk_FreeColor\fR will release it to the X server and delete it from
-the database.
-
+.VS 8.1
+When a color is no longer needed \fBTk_FreeColorFromObj\fR or
+\fBTk_FreeColor\fR should be called to release it.
+For \fBTk_FreeColorFromObj\fR the color to release is specified
+with the same information used to create it; for
+\fBTk_FreeColor\fR the color to release is specified
+with a pointer to its XColor structure.
+There should be exactly one call to \fBTk_FreeColorFromObj\fR
+or \fBTk_FreeColor\fR for each call to \fBTk_AllocColorFromObj\fR,
+\fBTk_GetColor\fR, or \fBTk_GetColorByValue\fR.
+.VE
 .SH KEYWORDS
-color, intensity, pixel value
+color, intensity, object, pixel value