Tk_Get3DBorder (3)
draw borders with
three-dimensional appearance
SYNOPSIS
#include <tk.h>
Tk_3DBorder
Tk_Get3DBorder(interp, tkwin, colorName)
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_Free3DBorder(border)
ARGUMENTS
"Tk_3DBorder" borderWidth
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).
Tk_Uid colorName in
Textual description of color corresponding to background (flat areas).
Illuminated edges will be brighter than this and shadowed edges will
be darker than this.
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
isn't).
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_Get3DBorder
allocates colors and Pixmaps needed to draw a border in the window
given by the tkwin argument. The colorName
argument indicates what colors should be used in the border.
ColorName may be any value acceptable to Tk_GetColor.
The color indicated by colorName 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 colorName, and the shadowed portions of the border will appear
darker than colorName.
Tk_Get3DBorder 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. colorName isn't a legal color specifier),
then NULL is returned and an error message is left in interp->result.
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 colorName 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 given by the colorName argument passed to
Tk_Get3DBorder 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 colorName string that was passed to
Tk_Get3DBorder 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 colorName passed to
Tk_Get3DBorder.
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_Free3DBorder should
be called to release the resources associated with the border.
There should be exactly one call to Tk_Free3DBorder for
each call to Tk_Get3DBorder.
KEYWORDS
3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect
'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: SetClass.3,v 1.2 1998/09/14 18:22:53 stanton Exp $
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\" Start paragraph describing an argument to a library procedure.
'\" type is type of argument (int, etc.), in/out is either "in", "out",
'\" or "in/out" to describe whether procedure reads or modifies arg,
'\" and indent is equivalent to second arg of .IP (shouldn't ever be
'\" needed; use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\" Give maximum sizes of arguments for setting tab stops. Type and
'\" name are examples of largest possible arguments that will be passed
'\" to .AP later. If args are omitted, default tab stops are used.
'\"
'\" .BS
'\" Start box enclosure. From here until next .BE, everything will be
'\" enclosed in one large box.
'\"
'\" .BE
'\" End of box enclosure.
'\"
'\" .CS
'\" Begin code excerpt.
'\"
'\" .CE
'\" End code excerpt.
'\"
'\" .VS ?version? ?br?
'\" Begin vertical sidebar, for use in marking newly-changed parts
'\" of man pages. The first argument is ignored and used for recording
'\" the version when the .VS was added, so that the sidebars can be
'\" found and removed when they reach a certain age. If another argument
'\" is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\" End of vertical sidebar.
'\"
'\" .DS
'\" Begin an indented unfilled display.
'\"
'\" .DE
'\" End of indented unfilled display.
'\"
'\" .SO
'\" Start of list of standard options for a Tk widget. The
'\" options follow on successive lines, in four columns separated
'\" by tabs.
'\"
'\" .SE
'\" End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\" Start of description of a specific option. cmdName gives the
'\" option's name as specified in the class command, dbName gives
'\" the option's name in the option database, and dbClass gives
'\" the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\" Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.2 1998/09/14 18:39:54 stanton Exp $
'\"
'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
t .wh -1.3i ^B
^l \n(.l
b
'\" # Start an argument description
AP
!"\\$4"" .TP \\$4
\{\
!"\\$2"" .TP \\n()Cu
.TP 15
|
