tk_alloc3dborderfromobtk3library procedtk_alloc3dborderfromobj(3)

NAME

Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorder
FromObj, 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_Get3DBor
der, must be the
window for which the
border was allo
cated).
Tcl_Obj *objPtr (in) Pointer to object: whose value
describes color cor
responding to back
ground (flat areas).
Illuminated edges
will be brighter
than this and shad
owed edges will be
darker than this.
char *color_ Name (in): Same as objPtr
except value is sup
plied as a string
rather than an
object.
Drawable drawable (in) X token for window: or pixmap; indi
cates 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, nega
tive means border is
outside rectangle.
int relief (in) Indicates 3-D posi: tion 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 isn't).
int numPoints (in) Number of points at: *pointPtr.
int polyBorderWidth(in) Width of border in: pixels. If posi
tive, border is
drawn to left of
trajectory given by
pointPtr; if nega
tive, border is
drawn to right of
trajectory. If
leftRelief is
TK_RELIEF_GROOVE or
TK_RELIEF_RIDGE then
the border is cen
tered on the trajec
tory.
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_Fill3DPoly
gon, TK_RELIEF_FLAT
may also be speci
fied 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 graph
ics 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 appear
ance. 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 bor
der; it indicates the background color for the window
(i.e. a color for flat surfaces). The illuminated por
tions 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 doesn't 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_Draw3DRectan
gle 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 nonself-intersecting, the appearance will be a raised or
sunken polygon shape. The trajectory may be self-inter
secting, 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 rectan
gle, and Tk_3DHorizontalBevel draws a horizontal beveled
edge, such as the top or bottom of a rectangle. Each pro
cedure 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_3DVerti
calBevel 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 result
ing 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_NameOf3DBor
der will return the color name that was used to create the
border.

The procedure Tk_3DBorderColor returns the XColor struc
ture 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

docs.sk

comprehensive documentation repository