summaryrefslogtreecommitdiffstats
path: root/doc/3DBorder.3
diff options
context:
space:
mode:
authorstanton <stanton>1999-04-16 01:51:06 (GMT)
committerstanton <stanton>1999-04-16 01:51:06 (GMT)
commit03656f44f81469f459031fa3a4a7b09c8bc77712 (patch)
tree31378e81bd58f8c726fc552d6b30cbf3ca07497b /doc/3DBorder.3
parent404fc236f34304df53b7e44bc7971d786b87d453 (diff)
downloadtk-03656f44f81469f459031fa3a4a7b09c8bc77712.zip
tk-03656f44f81469f459031fa3a4a7b09c8bc77712.tar.gz
tk-03656f44f81469f459031fa3a4a7b09c8bc77712.tar.bz2
* Merged 8.1 branch into the main trunk
Diffstat (limited to 'doc/3DBorder.3')
-rw-r--r--doc/3DBorder.3101
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