head	1.13;
access;
symbols
	core-8-5-9:1.11
	core-8-5-8:1.11
	macosx-cocoa-merge:1.13
	macosx-cocoa-premerge:1.13
	macosx-carbon-freeze:1.13
	core-8-5-7:1.11
	core-8-5-6:1.11
	core-8-6-b1:1.12
	core-8-6-a3:1.12
	core-8-5-5:1.11
	core-8-6-a2:1.12
	core-8-5-4:1.11
	core-8-5-3:1.11
	core-8-6-a1:1.11
	core-8-4-19:1.4
	core-8-5-branch:1.11.0.2
	core-8-5-2:1.11
	core-8-4-18:1.4
	core-8-5-1:1.11
	core-8-4-17:1.4
	core-8-5-0:1.11
	core-8-5-b3:1.10
	core-8-5-b2:1.9
	core-8-4-16:1.4
	core-8-5-b1:1.7
	core-stablilizer-merge:1.7
	core-stabilizer-branch:1.7.0.2
	core-stabilizer-merge:1.11
	core-8-4-15:1.4
	core-8-5-a6:1.7
	core-8-5-a5:1.6
	core-8-4-14:1.4
	core-8-5-a4:1.6
	core-8-4-13:1.4
	core-8-4-12:1.4
	core-8-4-11:1.4
	core-8-5-a3:1.6
	core-8-4-10:1.4
	core-8-4-9-branch:1.4.0.6
	core-8-5-a2:1.5
	core-8-4-9:1.4
	core-8-4-8:1.4
	core-8-4-7:1.4
	core-8-5-a1:1.4
	core-8-4-6:1.4
	core-8-4-5:1.4
	mistachkin-dev-branch:1.4.0.4
	core-8-4-4:1.4
	core-8-4-3:1.4
	core-8-4-branch:1.4.0.2
	core-8-4-2:1.4
	core-8-4-1:1.4
	core-8-3-5:1.3
	core-8-4-0:1.4
	macosx-8-4-merge-2002-08-31-trunk:1.4
	macosx-8-4-premerge-2002-08-31-branch:1.3.18.1
	macosx-8-4-premerge-2002-08-31-trunk:1.4
	macosx-8-4-merge-2002-08-30-branch:1.3.18.1
	macosx-8-4-merge-2002-08-30-trunk:1.4
	macosx-8-4-merge-2002-08-20-branch:1.3.18.1
	macosx-8-4-merge-2002-08-20-trunk:1.4
	core-8-4-b2:1.4
	core-8-4-b1:1.3
	macosx-premerge-6-9-02:1.3
	core-8-4-a4:1.3
	core-8-3-4:1.3
	macosx-8-4-branch:1.3.0.18
	macosx-8-4-branchpoint:1.3
	core-8-4-a3:1.3
	core-8-3-3:1.3
	dgp-privates-into-namespace:1.3.0.16
	tclpro-1-5-0:1.3
	core-8-4-win-speedup:1.3.0.14
	core-8-4-a2:1.3
	tclpro-1-4-1:1.3
	tclpro-1-4-0:1.3
	core-8-3-2:1.3
	ajuba-ajuba2-2-1-base:1.3
	ajuba-ajuba2-2-0:1.3
	core-8-4-a1:1.3
	core-8-3-1-branch:1.3.0.12
	core-8-3-1:1.3
	scriptics-sc-2-0-b5:1.3
	scriptics-sc-2-0-fixed:1.3
	scriptics-sc-2-0-b2:1.3
	scriptics-sc-2-0-b1:1.3
	core-8-3-0:1.3
	core-8-3-b2:1.3
	core-8-3-b1:1.3
	scriptics-sc-1-1:1.3
	scriptics-sc-1-1-b1:1.3
	core-8-2-3:1.3
	scriptics-sc-1-1-branch:1.3.0.10
	scriptics-sc-1-1-base:1.3
	scriptics-sc-1-0:1.3
	scriptics-sc-1-0-branch:1.3.0.8
	scriptics-sc-1-0-base:1.3
	core-8-2-2:1.3
	core-8-2-1:1.3
	scriptics-bc-1-0-b1:1.3
	core-8-2-1-branch:1.3.0.6
	scriptics-tclpro-1-3-0:1.3
	core-8-2-0:1.3
	core-8-2-b3-branch:1.3.0.4
	core-8-2-b3-base:1.3
	scriptics-tclpro-1-3-b4:1.3
	core-8-2-b2:1.3
	scriptics-tclpro-1-3-b3:1.3
	core-8-2-b1:1.3
	scriptics-tclpro-1-3-b2:1.3
	merge-to-mainline-5/21/99:1.3
	scriptics-tclpro-1-3-b2-branch:1.3.0.2
	core-8-1-1:1.3
	scriptics-tclpro-1-3-b1:1.3
	core-8-1-1-base:1.3
	core-8-1-0:1.3
	merge-to-mainline-4-29-99:1.3
	merge-to-mainline-4-23-99:1.3
	core-8-1-branch-old:1.1.0.4
	core-8-0-6-branch:1.2.0.6
	core-8-0-6-base:1.2
	core-8-0-5:1.2
	core-8-1-b3:1.1.4.2
	core-8-1-b2:1.1.4.2
	dev-8-1-stubs-branch:1.1.4.2.0.2
	dev-stubs-branch:1.2.0.4
	scriptics-tclpro-1-2:1.2
	scriptics-tclpro-1-2-b2:1.2
	core-8-1-merge-2/10/99:1.2
	core-8-0-5-branch:1.2.0.2
	core-8-0-5-base:1.2
	scriptics-tclpro-1-2-b1:1.2
	scriptics-tclpro-1-2-a1:1.2
	core-8-1-b1:1.1.4.2
	core-8-0-4:1.2
	core-8-1-a2:1.1.4.1
	core-8-0-2:1.1
	core-8-0-3:1.2;
locks; strict;
comment	@# @;


1.13
date	2009.05.04.09.12.33;	author dkf;	state Exp;
branches;
next	1.12;

1.12
date	2008.06.30.22.57.00;	author dkf;	state Exp;
branches;
next	1.11;

1.11
date	2007.12.13.15.23.42;	author dgp;	state Exp;
branches;
next	1.10;

1.10
date	2007.10.29.16.04.12;	author dkf;	state Exp;
branches;
next	1.9;

1.9
date	2007.10.26.20.13.22;	author dgp;	state Exp;
branches;
next	1.8;

1.8
date	2007.10.24.14.32.56;	author dkf;	state Exp;
branches;
next	1.7;

1.7
date	2007.01.05.00.00.48;	author nijtmans;	state Exp;
branches
	1.7.2.1;
next	1.6;

1.6
date	2005.04.06.21.11.53;	author dkf;	state Exp;
branches;
next	1.5;

1.5
date	2004.09.19.16.05.36;	author dkf;	state Exp;
branches;
next	1.4;

1.4
date	2002.08.05.04.30.38;	author dgp;	state Exp;
branches;
next	1.3;

1.3
date	99.04.16.01.51.07;	author stanton;	state Exp;
branches
	1.3.18.1;
next	1.2;

1.2
date	98.09.14.18.22.45;	author stanton;	state Exp;
branches;
next	1.1;

1.1
date	98.04.01.09.39.58;	author rjohnson;	state Exp;
branches
	1.1.4.1;
next	;

1.1.4.1
date	98.09.29.00.25.07;	author stanton;	state Exp;
branches;
next	1.1.4.2;

1.1.4.2
date	98.09.30.02.15.16;	author stanton;	state Exp;
branches;
next	;

1.3.18.1
date	2002.08.20.20.26.59;	author das;	state Exp;
branches;
next	;

1.7.2.1
date	2007.11.01.16.37.10;	author dgp;	state Exp;
branches;
next	;


desc
@@


1.13
log
@Purge mention of interp->result. [Bug 2431507]
@
text
@'\"
'\" Copyright (c) 1990-1993 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: 3DBorder.3,v 1.12 2008/06/30 22:57:00 dkf Exp $
'\" 
.so man.macros
.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
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
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
.sp
void
\fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
.sp
void
\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
.sp
void
\fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
.sp
void
\fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
.sp
void
\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR
.sp
void
\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR
.sp
void
\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR
.sp
const char *
\fBTk_NameOf3DBorder(\fIborder\fB)\fR
.sp
XColor *
\fBTk_3DBorderColor(\fIborder\fB)\fR
.sp
GC *
\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR
.sp
\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR
.sp
\fBTk_Free3DBorder(\fIborder\fB)\fR
.SH ARGUMENTS
.AS "Tk_3DBorder" borderWidth
.AP Tcl_Interp *interp in
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 Tcl_Obj *objPtr in
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.
.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
same screen and depth as \fItkwin\fR.
.AP Tk_3DBorder border in
Token for border previously allocated in call to \fBTk_Get3DBorder\fR.
.AP int x in
X-coordinate of upper-left corner of rectangle describing border
or bevel, in pixels.
.AP int y in
Y-coordinate of upper-left corner of rectangle describing border or
bevel, in pixels.
.AP int width in
Width of rectangle describing border or bevel, in pixels.
.AP int height in
Height of rectangle describing border or bevel, in pixels.
.AP int borderWidth in
Width of border in pixels. Positive means border is inside rectangle
given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means
border is outside rectangle.
.AP int relief in
Indicates 3-D position of interior of object relative to exterior;
should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR,
\fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR (may also be \fBTK_RELIEF_FLAT\fR
for \fBTk_Fill3DRectangle\fR).
.AP XPoint *pointPtr in
Pointer to array of points describing the set of vertices in a polygon.
The polygon need not be closed (it will be closed automatically if it
is not).
.AP int numPoints in
Number of points at \fI*pointPtr\fR.
.AP int polyBorderWidth in
Width of border in pixels.  If positive, border is drawn to left of
trajectory given by \fIpointPtr\fR;  if negative, border is drawn to
right of trajectory.  If \fIleftRelief\fR is \fBTK_RELIEF_GROOVE\fR or
\fBTK_RELIEF_RIDGE\fR then the border is centered on the trajectory.
.AP int leftRelief in
Height of left side of polygon's path relative to right.  \fBTK_RELIEF_RAISED\fR
means left side should appear higher and \fBTK_RELIEF_SUNKEN\fR means right side
should appear higher;
\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean the obvious things.
For \fBTk_Fill3DPolygon\fR, \fBTK_RELIEF_FLAT\fR may also be specified to
indicate no difference in height.
.AP int leftBevel in
Non-zero means this bevel forms the left side of the object;  zero means
it forms the right side.
.AP int leftIn in
Non-zero means that the left edge of the horizontal bevel angles in,
so that the bottom of the edge is farther to the right than
the top.
Zero means the edge angles out, so that the bottom is farther to the
left than the top.
.AP int rightIn in
Non-zero means that the right edge of the horizontal bevel angles in,
so that the bottom of the edge is farther to the left than the top.
Zero means the edge angles out, so that the bottom is farther to the
right than the top.
.AP int topBevel in
Non-zero means this bevel forms the top side of the object;  zero means
it forms the bottom side.
.AP int which in
Specifies which of the border's graphics contexts is desired.
Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR.
.BE
.SH DESCRIPTION
.PP
These procedures provide facilities for drawing window borders in a
way that produces a three-dimensional appearance.
\fBTk_Alloc3DBorderFromObj\fR
allocates colors and Pixmaps needed to draw a border in the window
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 \fIobjPtr\fR, and the shadowed portions of the border will appear
darker than \fIobjPtr\fR.
.PP
\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. a bogus color name was given)
then NULL is returned and an error message is left as the result of
interpreter \fIinterp\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 does not 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.
.PP
Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be
invoked to draw the border.
The \fItkwin\fR argument specifies the
window for which the border was allocated, and \fIdrawable\fR
specifies a window or pixmap in which the border is to be drawn.
\fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it
must refer to a compatible
pixmap or window:  one associated with the same screen and with the
same depth as \fItkwin\fR.
The \fIx\fR, \fIy\fR, \fIwidth\fR, and
\fIheight\fR arguments define the bounding box of the border region
within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and
\fIwidth\fR and \fIheight\fR are the dimensions of the window), and
\fIborderWidth\fR specifies the number of pixels actually
occupied by the border.  The \fIrelief\fR argument indicates
which of several three-dimensional effects is desired:
\fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should
appear raised relative to the exterior of the rectangle, and
\fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed.
\fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean that there should appear to be
a groove or ridge around the exterior of the rectangle.
.PP
\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 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 (\fBTK_RELIEF_FLAT\fR means no border should be drawn; all that
happens is to fill the rectangle with the background color).
.PP
The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex
shapes with a three-dimensional appearance.  The \fIpointPtr\fR and
\fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR
indicates how wide the border should be (and on which side of the
trajectory to draw it), and \fIleftRelief\fR indicates which side
of the trajectory should appear raised.  \fBTk_Draw3DPolygon\fR
draws a border around the given trajectory using the colors from
\fIborder\fR to produce a three-dimensional appearance.  If the trajectory is
non-self-intersecting, the appearance will be a raised or sunken
polygon shape.  The trajectory may be self-intersecting, although
it's not clear how useful this is.
.PP
\fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what
\fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR:  it fills
the polygonal area with the background color from \fIborder\fR,
then calls \fBTk_Draw3DPolygon\fR to draw a border around the
area (unless \fIleftRelief\fR is \fBTK_RELIEF_FLAT\fR; in this case no
border is drawn).
.PP
The procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fR
provide lower-level drawing primitives that are used by
procedures such as \fBTk_Draw3DRectangle\fR.
These procedures are also useful in their own right for drawing
rectilinear border shapes.
\fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as the
left or right side of a rectangle, and \fBTk_3DHorizontalBevel\fR
draws a horizontal beveled edge, such as the top or bottom of a
rectangle.
Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR
arguments that describe the rectangular area of the beveled edge
(e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR).
The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the
position of the border relative to the
.QW inside
of the object, and
\fIrelief\fR indicates the relief of the inside of the object relative
to the outside.
\fBTk_3DVerticalBevel\fR just draws a rectangular region.
\fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate
mitered corners;  it should be called after \fBTk_3DVerticalBevel\fR
(otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering in
the corner).
The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fR
describe the mitering at the corners;  a value of 1 means that the bottom
edge of the trapezoid will be shorter than the top, 0 means it will
be longer.
For example, to draw a rectangular border the top bevel should be
drawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and the
bottom bevel should be drawn with 0 for both arguments.
.PP
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 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 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 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
The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts
that are used to draw the border.
The argument \fIwhich\fR selects which one of the three possible GC's:
\fBTK_3D_FLAT_GC\fR returns the context used for flat surfaces,
\fBTK_3D_LIGHT_GC\fR returns the context for light shadows,
and \fBTK_3D_DARK_GC\fR returns the context for dark shadows.
.PP
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.
.SH KEYWORDS
3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect
@


1.12
log
@Minor doc updates (removing out of date changebars, improving typedef formatting,
 etc.)
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: 3DBorder.3,v 1.11 2007/12/13 15:23:42 dgp Exp $
d157 2
a158 1
then NULL is returned and an error message is left in \fIinterp->result\fR.
@


1.11
log
@merge stable branch onto HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: 3DBorder.3,v 1.7.2.1 2007/11/01 16:37:10 dgp Exp $
a138 1

a293 1

@


1.10
log
@Lots more GOOBE stuff. Now works with 'make html'!
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: 3DBorder.3,v 1.9 2007/10/26 20:13:22 dgp Exp $
@


1.9
log
@        * doc/*.1:              Revert doc changes that broke
        * doc/*.3:              `make html` so we can get the release
        * doc/*.n:              out the door.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: 3DBorder.3,v 1.7 2007/01/05 00:00:48 nijtmans Exp $
d103 1
a103 1
isn't).
d171 1
a171 1
\fBTk_Get3DBorderFromObj\fR doesn't actually create the border; it must
d241 3
a243 1
position of the border relative to the ``inside'' of the object, and
@


1.8
log
@Lots of improvements to look and feel of manual pages
@
text
@d241 1
a241 3
position of the border relative to the
.QW inside
of the object, and
@


1.7
log
@various "const" additions, in line with TIP #27
fix bug #1627732
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: 3DBorder.3,v 1.6 2005/04/06 21:11:53 dkf Exp $
d241 3
a243 1
position of the border relative to the ``inside'' of the object, and
@


1.7.2.1
log
@merge updates from HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: 3DBorder.3,v 1.7 2007/01/05 00:00:48 nijtmans Exp $
d103 1
a103 1
is not).
d171 1
a171 1
\fBTk_Get3DBorderFromObj\fR does not actually create the border; it must
d241 1
a241 3
position of the border relative to the
.QW inside
of the object, and
@


1.6
log
@Purge old and inaccurate .VS/.VE macros.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: 3DBorder.3,v 1.5 2004/09/19 16:05:36 dkf Exp $
d49 1
a49 1
CONST char *
@


1.5
log
@Standardize style of section refs & public symbols. Remove displayed tabs
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: 3DBorder.3,v 1.4 2002/08/05 04:30:38 dgp Exp $
a18 1
.VS 8.1
a26 1
.VE
a57 1
.VS 8.1
a58 1
.VE
a68 1
.VS 8.1
a74 1
.VE
a143 1
.VS 8.1
a176 1
.VE
a282 1
.VS 8.1
a292 1
.VE
@


1.4
log
@Applied companion patch for Tcl Patch 585105,
updating Tk to use Tcl 8.4's fully CONST-ified
interface, and fully CONSTifying Tk at the
same time.

This patch includes purging Tk of its last
direct access to interp->result.  [Bug 589853]

The substantial changes include copying
event sequence strings into Tcl_DStrings
in tkBind.c, and copying [text] indices into
Tcl_DStrings because parsing them involved
overwriting them.  If this causes performance
trouble, that can be resolved by further
converting them to Tcl_Obj's.

The #defines USE_NON_CONST and USE_COMPAT_CONST
have the same effect for Tk as they do for Tcl.
(They actually change tcl.h)
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: 3DBorder.3,v 1.3 1999/04/16 01:51:07 stanton Exp $
d103 2
a104 2
should be TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, 
TK_RELIEF_SOLID, or TK_RELIEF_RIDGE (may also be TK_RELIEF_FLAT
d115 2
a116 2
right of trajectory.  If \fIleftRelief\fR is TK_RELIEF_GROOVE or
TK_RELIEF_RIDGE then the border is centered on the trajectory.
d118 2
a119 2
Height of left side of polygon's path relative to right.  TK_RELIEF_RAISED
means left side should appear higher and TK_RELIEF_SUNKEN means right side
d121 2
a122 2
TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things.
For \fBTk_Fill3DPolygon\fR, TK_RELIEF_FLAT may also be specified to
d143 1
a143 1
Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC.
d202 4
a205 4
TK_RELIEF_RAISED means that the interior of the rectangle should appear raised
relative to the exterior of the rectangle, and
TK_RELIEF_SUNKEN means that the interior should appear depressed.
TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to be
d214 1
a214 1
effect (TK_RELIEF_FLAT means no border should be drawn; all that
d233 1
a233 1
area (unless \fIleftRelief\fR is TK_RELIEF_FLAT;  in this case no
d287 3
a289 3
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.
@


1.3
log
@* Merged 8.1 branch into the main trunk
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id$
d51 1
a51 1
char *
@


1.3.18.1
log
@merged with trunk at tag macosx-8-4-merge-2002-08-20-trunk
@
text
@d51 1
a51 1
CONST char *
@


1.2
log
@Replaced SCCS strings, fixed binary files
@
text
@d3 1
a3 1
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
d11 1
a11 1
.TH Tk_Get3DBorder 3 4.0 Tk "Tk Library Procedures"
d14 1
a14 1
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
d19 4
d26 4
d60 4
d72 9
a80 4
.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.
d149 3
a151 1
way that produces a three-dimensional appearance.  \fBTk_Get3DBorder\fR
d153 3
a155 4
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
d159 2
a160 2
by \fIcolorName\fR, and the shadowed portions of the border will appear
darker than \fIcolorName\fR.
d162 1
a162 1
\fBTk_Get3DBorder\fR returns a token that may be used in later calls
d164 1
a164 1
for the border (e.g. \fIcolorName\fR isn't a legal color specifier),
d166 19
d211 1
a211 1
to the \fIcolorName\fR used to create \fIborder\fR).  Then it calls
d268 1
a268 2
just be the color given by the \fIcolorName\fR argument passed to
\fBTk_Get3DBorder\fR when \fIborder\fR was created;  for monochrome
d274 1
a274 2
will return the \fIcolorName\fR string that was passed to
\fBTk_Get3DBorder\fR to create the border.
d279 2
a280 2
The return value corresponds to the \fIcolorName\fR passed to
\fBTk_Get3DBorder\fR.
d291 12
a302 4
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.
d305 1
a305 1
3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect
@


1.1
log
@Initial revision
@
text
@d8 1
a8 1
'\" SCCS: @@(#) 3DBorder.3 1.23 96/11/17 15:03:05
@


1.1.4.1
log
@initial tk8.1a2 version
@
text
@d3 1
a3 1
'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
d8 1
a8 1
'\" SCCS: @@(#) 3DBorder.3 1.25 98/01/14 13:58:56
d11 1
a11 1
.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures"
d14 1
a14 1
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
a18 4
.VS 8.1
Tk_3DBorder
\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR
.sp
a21 4
Tk_3DBorder
\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR
.VE
.sp
a51 4
.VS 8.1
\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR
.VE
.sp
d60 4
a63 9
.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
d132 1
a132 3
way that produces a three-dimensional appearance.
.VS 8.1
\fBTk_Alloc3DBorderFromObj\fR
d134 4
a137 3
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
d141 2
a142 2
by \fIobjPtr\fR, and the shadowed portions of the border will appear
darker than \fIobjPtr\fR.
d144 1
a144 1
\fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls
d146 1
a146 1
for the border (e.g. a bogus color name was given)
a147 19
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
d174 1
a174 1
to the color used to create \fIborder\fR).  Then it calls
d231 2
a232 1
just be the color specified when \fIborder\fR was created;  for monochrome
d238 2
a239 1
will return the color name that was used to create the border.
d244 2
a245 2
The return value corresponds to the color name that was used to
create the border.
d256 4
a259 12
.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
d262 1
a262 1
3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect
@


1.1.4.2
log
@Merged 8.0.3 changes into 8.1
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: 3DBorder.3,v 1.2 1998/09/14 18:22:45 stanton Exp $
@


