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)
char *
Tk_NameOf3DBorder(border)
XColor *
Tk_3DBorderColor(border)
GC *
Tk_3DBorderGC(tkwin, border, which)
Tk_Free3DBorderFromObj(tkwin, objPtr) |
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 *colorName (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
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
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
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 success |
fully, 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; 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 non-
self-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
(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
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
Man(1) output converted with
man2html