Tk_Get3DBorder(3Tk)Tk_Get3DBorder(3Tk)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
SYNOPSIS
#include <tk.h>
Tk_3DBorder
Tk_Get3DBorder(interp, tkwin, colorName) |
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)
char *
Tk_NameOf3DBorder(border)
XColor *
Tk_3DBorderColor(border)
GC * |
Tk_3DBorderGC(tkwin, border, which) |
Tk_Free3DBorder(border)
Page 1
Tk_Get3DBorder(3Tk)Tk_Get3DBorder(3Tk)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).
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.
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 object relative to exterior;
should be TK_RELIEF_RAISED,
TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE,
or TK_RELIEF_RIDGE (may also be
TK_RELIEF_FLAT for
Tk_Fill3DRectangle).
Page 2
Tk_Get3DBorder(3Tk)Tk_Get3DBorder(3Tk)
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 isn't).
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 object; 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.
Page 3
Tk_Get3DBorder(3Tk)Tk_Get3DBorder(3Tk)
int topBevel (in) Non-zero means this bevel forms the|
top side of the object; 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_Get3DBorder allocates
colors and Pixmaps needed to draw a border in the window given by the
tkwin argument. The colorName argument indicates what colors should be
used in the border. ColorName may be any value acceptable to
Tk_GetColor. The color indicated by colorName 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 colorName, and the shadowed portions of
the border will appear darker than colorName.
Tk_Get3DBorder 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. colorName isn't a legal color specifier), then NULL is
returned and an error message is left in interp->result.
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 colorName 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).
Page 4
Tk_Get3DBorder(3Tk)Tk_Get3DBorder(3Tk)
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 object, and relief indicates the relief of the inside |
of the object 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 given by
the colorName argument passed to Tk_Get3DBorder 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 colorName string that was passed to Tk_Get3DBorder to create the
border.
Page 5
Tk_Get3DBorder(3Tk)Tk_Get3DBorder(3Tk)
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 colorName passed
to Tk_Get3DBorder. 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_Free3DBorder should be called to
release the resources associated with the border. There should be
exactly one call to Tk_Free3DBorder for each call to Tk_Get3DBorder.
KEYWORDS
3D, background, border, color, depressed, illumination, polygon, raised,
shadow, three-dimensional effect
Page 6
