Tk_Alloc3DBorderFromObj(3) Tk Library Procedures Tk_Alloc3DBorderFromObj(3)

____________________________________________________________________________

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)

Tk_Draw3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)

Tk_Fill3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)

Tk_Draw3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)

Tk_Fill3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)

Tk_3DVerticalBevel(tkwin, drawable, border, x, y, width, height, leftBevel, relief)

Tk_3DHorizontalBevel(tkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief)

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.

const 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

Tk 8.1 Tk_Alloc3DBorderFromObj(3)