Tk_3DBorderGC(3tk)
Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_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)
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 Last change: 8.1 1
Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)
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 pre-
viously allocated in
call to
Tk_Get3DBorder.
int x (in) X-coordinate of
upper-left corner of
rectangle describing
border or bevel, in
pixels.
Tk Last change: 8.1 2
Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)
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 rec-
tangle given by x, y,
width, height, nega-
tive 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
Tk Last change: 8.1 3
Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)
negative, border is
drawn to right of tra-
jectory. If leftRe-
lief 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 rela-
tive 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 bot-
tom 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
Tk Last change: 8.1 4
Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)
means the edge angles
out, so that the bot-
tom 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 con-
texts 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 bord-
ers 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 deter-
mines the border colors. The color indicated by objPtr will
not actually be used in the border; it indicates the back-
ground color for the window (i.e. a color for flat sur-
faces). 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
Tk Last change: 8.1 5
Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)
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 indi-
cates 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 rectan-
gle, 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 com-
plex 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
Tk Last change: 8.1 6
Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)
is drawn).
The procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel
provide lower-level drawing primitives that are used by pro-
cedures 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 rec-
tangular 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 Last change: 8.1 7
Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)
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
Tk Last change: 8.1 8
Man(1) output converted with
man2html