Tk Source Code

.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

.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).

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

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

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

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

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
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:
.TP 20
\fIcolorname\fR
Any of the valid textual names for a color defined in the
server's color database file, such as \fBred\fR or \fBPeachPuff\fR.
.TP 20
\fB#\fIRGB\fR
.TP 20

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 does not actually create the color; the color
must already have been created with a previous call to

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.
.SH KEYWORDS
color, intensity, object, pixel value