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 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.
- char *colorName (in)
- Same as objPtr except value is supplied as a string rather than an
object.
- 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, 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 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.
- 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_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 in
interp->result. 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 an object. 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 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 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, object, polygon, raised,
shadow, three-dimensional effect