* Merged 8.1 branch into the main trunk

1 files changed, 72 insertions, 29 deletions

diff --git a/doc/3DBorder.3 b/doc/3DBorder.3
index ea1a629..2780bde 100644
--- a/doc/3DBorder.3
+++ b/doc/3DBorder.3
@@ -1,24 +1,32 @@
 '\"
 '\" Copyright (c) 1990-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" 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: 3DBorder.3,v 1.2 1998/09/14 18:22:45 stanton Exp $
+'\" RCS: @(#) $Id: 3DBorder.3,v 1.3 1999/04/16 01:51:07 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_Get3DBorder 3 4.0 Tk "Tk Library Procedures"
+.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_Get3DBorder, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorder \- draw borders with three-dimensional appearance
+Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
+.VS 8.1
+Tk_3DBorder
+\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
 Tk_3DBorder
 \fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR
 .sp
+Tk_3DBorder
+\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
 void
 \fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
 .sp
@@ -49,6 +57,10 @@ XColor *
 GC *
 \fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR
 .sp
+.VS 8.1
+\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
 \fBTk_Free3DBorder(\fIborder\fB)\fR
 .SH ARGUMENTS
 .AS "Tk_3DBorder" borderWidth
@@ -57,10 +69,15 @@ Interpreter to use for error reporting.
 .AP Tk_Window tkwin in
 Token for window (for all procedures except \fBTk_Get3DBorder\fR,
 must be the window for which the border was allocated).
-.AP Tk_Uid colorName in
-Textual description of color corresponding to background (flat areas).
-Illuminated edges will be brighter than this and shadowed edges will
-be darker than this.
+.AP Tcl_Obj *objPtr in
+.VS 8.1
+Pointer to object whose value describes color corresponding to
+background (flat areas).  Illuminated edges will be brighter than
+this and shadowed edges will be darker than this.
+.AP char *colorName in
+Same as \fIobjPtr\fR except value is supplied as a string rather
+than an object.
+.VE
 .AP Drawable drawable in
 X token for window or pixmap;  indicates where graphics are to be drawn.
 Must either be the X window for \fItkwin\fR or a pixmap with the
@@ -129,22 +146,42 @@ Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC.
 .SH DESCRIPTION
 .PP
 These procedures provide facilities for drawing window borders in a
-way that produces a three-dimensional appearance.  \fBTk_Get3DBorder\fR
+way that produces a three-dimensional appearance.
+.VS 8.1
+\fBTk_Alloc3DBorderFromObj\fR
 allocates colors and Pixmaps needed to draw a border in the window
-given by the \fItkwin\fR argument.  The \fIcolorName\fR
-argument indicates what colors should be used in the border.
-\fIColorName\fR may be any value acceptable to \fBTk_GetColor\fR.
-The color indicated by \fIcolorName\fR will not actually be used in
+given by the \fItkwin\fR argument.  The value of \fIobjPtr\fR
+is a standard Tk color name that determines the border colors.
+The color indicated by \fIobjPtr\fR will not actually be used in
 the border;  it indicates the background color for the window
 (i.e. a color for flat surfaces).
 The illuminated portions of the border will appear brighter than indicated
-by \fIcolorName\fR, and the shadowed portions of the border will appear
-darker than \fIcolorName\fR.
+by \fIobjPtr\fR, and the shadowed portions of the border will appear
+darker than \fIobjPtr\fR.
 .PP
-\fBTk_Get3DBorder\fR returns a token that may be used in later calls
+\fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls
 to \fBTk_Draw3DRectangle\fR.  If an error occurs in allocating information
-for the border (e.g. \fIcolorName\fR isn't a legal color specifier),
+for the border (e.g. a bogus color name was given)
 then NULL is returned and an error message is left in \fIinterp->result\fR.
+If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches
+information about the return value in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.PP
+\fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except
+that the color is specified with a string instead of an object.  This
+prevents \fBTk_Get3DBorder\fR from caching the return value, so
+\fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR.
+.PP
+\fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given
+the window and color name used to create the border.
+\fBTk_Get3DBorderFromObj\fR doesn't actually create the border; it must
+already have been created with a previous call to
+\fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.VE
 .PP
 Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be
 invoked to draw the border.
@@ -171,7 +208,7 @@ a groove or ridge around the exterior of the rectangle.
 \fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except
 that it first fills the rectangular area with the background color
 (one corresponding
-to the \fIcolorName\fR used to create \fIborder\fR).  Then it calls
+to the color used to create \fIborder\fR).  Then it calls
 \fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of
 the rectangular area.  The argument \fIrelief\fR indicates the desired
 effect (TK_RELIEF_FLAT means no border should be drawn; all that
@@ -228,21 +265,19 @@ bottom bevel should be drawn with 0 for both arguments.
 The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background
 pixel and/or pixmap of \fItkwin\fR to produce a result compatible
 with \fIborder\fR.  For color displays, the resulting background will
-just be the color given by the \fIcolorName\fR argument passed to
-\fBTk_Get3DBorder\fR when \fIborder\fR was created;  for monochrome
+just be the color specified when \fIborder\fR was created;  for monochrome
 displays, the resulting background
 will be a light stipple pattern, in order to distinguish the background from
 the illuminated portion of the border.
 .PP
 Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR
-will return the \fIcolorName\fR string that was passed to
-\fBTk_Get3DBorder\fR to create the border.
+will return the color name that was used to create the border.
 .PP
 The procedure \fBTk_3DBorderColor\fR returns the XColor structure
 that will be used for flat surfaces drawn for its \fIborder\fR
 argument by procedures like \fBTk_Fill3DRectangle\fR.
-The return value corresponds to the \fIcolorName\fR passed to
-\fBTk_Get3DBorder\fR.
+The return value corresponds to the color name that was used to
+create the border.
 The XColor, and its associated pixel value, will remain allocated
 as long as \fIborder\fR exists.
 .PP
@@ -253,10 +288,18 @@ TK_3D_FLAT_GC returns the context used for flat surfaces,
 TK_3D_LIGHT_GC returns the context for light shadows,
 and TK_3D_DARK_GC returns the context for dark shadows.
 .PP
-When a border is no longer needed, \fBTk_Free3DBorder\fR should
-be called to release the resources associated with the border.
-There should be exactly one call to \fBTk_Free3DBorder\fR for
-each call to \fBTk_Get3DBorder\fR.
+.VS 8.1
+When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR
+or \fBTk_Free3DBorder\fR should
+be called to release the resources associated with it.
+For \fBTk_Free3DBorderFromObj\fR the border to release is specified
+with the window and color name used to create the
+border; for \fBTk_Free3DBorder\fR the border to release is specified
+with the Tk_3DBorder token for the border.
+There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or
+\fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR
+or \fBTk_Get3DBorder\fR.
+.VE
 
 .SH KEYWORDS
-3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect
+3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect