Provided by: tk8.6-doc_8.6.13-2_all 
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
SYNOPSIS
#include <tk.h>
Tk_3DBorder
Tk_Alloc3DBorderFromObj(interp, tkwin, objPtr)
Tk_3DBorder
Tk_Get3DBorder(interp, tkwin, colorName)
Tk_3DBorder
Tk_Get3DBorderFromObj(tkwin, objPtr)
void
Tk_Draw3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)
void
Tk_Fill3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)
void
Tk_Draw3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)
void
Tk_Fill3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)
void
Tk_3DVerticalBevel(tkwin, drawable, border, x, y, width, height, leftBevel, relief)
void
Tk_3DHorizontalBevel(tkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief)
void
Tk_SetBackgroundFromBorder(tkwin, border)
const char *
Tk_NameOf3DBorder(border)
XColor *
Tk_3DBorderColor(border)
GC *
Tk_3DBorderGC(tkwin, border, which)
Tk_Free3DBorderFromObj(tkwin, objPtr)
Tk_Free3DBorder(border)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter to use for error reporting.
Tk_Window tkwin (in) Token for window (for all procedures except
Tk_Get3DBorder, must be the window for which the
border was allocated).
Tcl_Obj *objPtr (in) Pointer to value whose value describes color
corresponding to background (flat areas).
Illuminated edges will be brighter than this and
shadowed edges will be darker than this.
char *colorName (in) Same as objPtr except value is supplied as a string
rather than a value.
Drawable drawable (in) X token for window or pixmap; indicates where
graphics are to be drawn. Must either be the X
window for tkwin or a pixmap with the same screen
and depth as tkwin.
Tk_3DBorder border (in) Token for border previously allocated in call to
Tk_Get3DBorder.
int x (in) X-coordinate of upper-left corner of rectangle
describing border or bevel, in pixels.
int y (in) Y-coordinate of upper-left corner of rectangle
describing border or bevel, in pixels.
int width (in) Width of rectangle describing border or bevel, in
pixels.
int height (in) Height of rectangle describing border or bevel, in
pixels.
int borderWidth (in) Width of border in pixels. Positive means border is
inside rectangle given by x, y, width, height,
negative means border is outside rectangle.
int relief (in) Indicates 3-D position of interior of value relative
to exterior; should be TK_RELIEF_RAISED,
TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, TK_RELIEF_SOLID,
or TK_RELIEF_RIDGE (may also be TK_RELIEF_FLAT for
Tk_Fill3DRectangle).
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).
int numPoints (in) Number of points at *pointPtr.
int polyBorderWidth (in) Width of border in pixels. If positive, border is
drawn to left of trajectory given by pointPtr; if
negative, border is drawn to right of trajectory.
If leftRelief is TK_RELIEF_GROOVE or TK_RELIEF_RIDGE
then the border is centered on the trajectory.
int leftRelief (in) 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
should appear higher; TK_RELIEF_GROOVE and
TK_RELIEF_RIDGE mean the obvious things. For
Tk_Fill3DPolygon, TK_RELIEF_FLAT may also be
specified to indicate no difference in height.
int leftBevel (in) Non-zero means this bevel forms the left side of the
value; zero means it forms the right side.
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.
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.
int topBevel (in) Non-zero means this bevel forms the top side of the
value; zero means it forms the bottom side.
int which (in) Specifies which of the border's graphics contexts is
desired. Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or
TK_3D_DARK_GC.
_________________________________________________________________________________________________
DESCRIPTION
These procedures provide facilities for drawing window borders in a way that produces a
three-dimensional appearance. Tk_Alloc3DBorderFromObj allocates colors and Pixmaps needed
to draw a border in the window given by the tkwin argument. The value of objPtr is a
standard Tk color name that determines the border colors. The color indicated by objPtr
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 objPtr, and the shadowed portions of the border will appear
darker than objPtr.
Tk_Alloc3DBorderFromObj returns a token that may be used in later calls to
Tk_Draw3DRectangle. 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 interp. If it returns successfully, Tk_Alloc3DBorderFromObj caches
information about the return value in objPtr, which speeds up future calls to
Tk_Alloc3DBorderFromObj with the same objPtr and tkwin.
Tk_Get3DBorder is identical to Tk_Alloc3DBorderFromObj except that the color is specified
with a string instead of a value. This prevents Tk_Get3DBorder from caching the return
value, so Tk_Get3DBorder is less efficient than Tk_Alloc3DBorderFromObj.
Tk_Get3DBorderFromObj returns the token for an existing border, given the window and color
name used to create the border. Tk_Get3DBorderFromObj does not actually create the
border; it must already have been created with a previous call to Tk_Alloc3DBorderFromObj
or Tk_Get3DBorder. The return value is cached in objPtr, which speeds up future calls to
Tk_Get3DBorderFromObj with the same objPtr and tkwin.
Once a border structure has been created, Tk_Draw3DRectangle may be invoked to draw the
border. The tkwin argument specifies the window for which the border was allocated, and
drawable specifies a window or pixmap in which the border is to be drawn. Drawable need
not refer to the same window as tkwin, but it must refer to a compatible pixmap or window:
one associated with the same screen and with the same depth as tkwin. The x, y, width,
and height arguments define the bounding box of the border region within drawable (usually
x and y are zero and width and height are the dimensions of the window), and borderWidth
specifies the number of pixels actually occupied by the border. The relief argument
indicates which of several three-dimensional effects is desired: 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 a groove or ridge
around the exterior of the rectangle.
Tk_Fill3DRectangle is somewhat like Tk_Draw3DRectangle except that it first fills the
rectangular area with the background color (one corresponding to the color used to create
border). Then it calls Tk_Draw3DRectangle to draw a border just inside the outer edge of
the rectangular area. The argument relief indicates the desired effect (TK_RELIEF_FLAT
means no border should be drawn; all that happens is to fill the rectangle with the
background color).
The procedure Tk_Draw3DPolygon may be used to draw more complex shapes with a three-
dimensional appearance. The pointPtr and numPoints arguments define a trajectory,
polyBorderWidth indicates how wide the border should be (and on which side of the
trajectory to draw it), and leftRelief indicates which side of the trajectory should
appear raised. Tk_Draw3DPolygon draws a border around the given trajectory using the
colors from border 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.
Tk_Fill3DPolygon is to Tk_Draw3DPolygon what Tk_Fill3DRectangle is to Tk_Draw3DRectangle:
it fills the polygonal area with the background color from border, then calls
Tk_Draw3DPolygon to draw a border around the area (unless leftRelief is TK_RELIEF_FLAT; in
this case no border is drawn).
The procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel provide lower-level drawing
primitives that are used by procedures such as Tk_Draw3DRectangle. These procedures are
also useful in their own right for drawing rectilinear border shapes. Tk_3DVerticalBevel
draws a vertical beveled edge, such as the left or right side of a rectangle, and
Tk_3DHorizontalBevel draws a horizontal beveled edge, such as the top or bottom of a
rectangle. Each procedure takes x, y, width, and height arguments that describe the
rectangular area of the beveled edge (e.g., width is the border width for
Tk_3DVerticalBevel). The leftBorder and topBorder arguments indicate the position of the
border relative to the “inside” of the value, and relief indicates the relief of the
inside of the value relative to the outside. Tk_3DVerticalBevel just draws a rectangular
region. Tk_3DHorizontalBevel draws a trapezoidal region to generate mitered corners; it
should be called after Tk_3DVerticalBevel (otherwise Tk_3DVerticalBevel will overwrite the
mitering in the corner). The leftIn and rightIn arguments to Tk_3DHorizontalBevel
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 leftIn and rightIn, and
the bottom bevel should be drawn with 0 for both arguments.
The procedure Tk_SetBackgroundFromBorder will modify the background pixel and/or pixmap of
tkwin to produce a result compatible with border. For color displays, the resulting
background will just be the color specified when border 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.
Given a token for a border, the procedure Tk_NameOf3DBorder will return the color name
that was used to create the border.
The procedure Tk_3DBorderColor returns the XColor structure that will be used for flat
surfaces drawn for its border argument by procedures like Tk_Fill3DRectangle. 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 border exists.
The procedure Tk_3DBorderGC returns one of the X graphics contexts that are used to draw
the border. The argument which selects which one of the three possible GC's:
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.
When a border is no longer needed, Tk_Free3DBorderFromObj or Tk_Free3DBorder should be
called to release the resources associated with it. For Tk_Free3DBorderFromObj the border
to release is specified with the window and color name used to create the border; for
Tk_Free3DBorder the border to release is specified with the Tk_3DBorder token for the
border. There should be exactly one call to Tk_Free3DBorderFromObj or Tk_Free3DBorder for
each call to Tk_Alloc3DBorderFromObj or Tk_Get3DBorder.
KEYWORDS
3D, background, border, color, depressed, illumination, value, polygon, raised, shadow,
three-dimensional effect