通讯编程

开发平台：
Visual C++

3DBorder.3：源码内容
							'"
'" Copyright (c) 1990-1993 The Regents of the University of California.
'" Copyright (c) 1994-1998 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: 3DBorder.3,v 1.4 2002/08/05 04:30:38 dgp Exp $
'" 
.so man.macros
.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH 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
.SH SYNOPSIS
.nf
fB#include <tk.h>fR
.sp
.VS 8.1
Tk_3DBorder
fBTk_Alloc3DBorderFromObj(fIinterp, tkwin, objPtrfB)fR
.sp
Tk_3DBorder
fBTk_Get3DBorder(fIinterp, tkwin, colorNamefB)fR
.sp
Tk_3DBorder
fBTk_Get3DBorderFromObj(fItkwin, objPtrfB)fR
.VE
.sp
void
fBTk_Draw3DRectangle(fItkwin, drawable, border, x, y, width, height, borderWidth, relieffB)fR
.sp
void
fBTk_Fill3DRectangle(fItkwin, drawable, border, x, y, width, height, borderWidth, relieffB)fR
.sp
void
fBTk_Draw3DPolygon(fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelieffB)fR
.sp
void
fBTk_Fill3DPolygon(fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelieffB)fR
.sp
void
fBTk_3DVerticalBevelfR(fItkwin, drawable, border, x, y, width, height, leftBevel, relieffB)fR
.sp
void
fBTk_3DHorizontalBevelfR(fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relieffB)fR
.sp
void
fBTk_SetBackgroundFromBorder(fItkwin, borderfB)fR
.sp
CONST char *
fBTk_NameOf3DBorder(fIborderfB)fR
.sp
XColor *
fBTk_3DBorderColor(fIborderfB)fR
.sp
GC *
fBTk_3DBorderGC(fItkwin, border, whichfB)fR
.sp
.VS 8.1
fBTk_Free3DBorderFromObj(fItkwin, objPtrfB)fR
.VE
.sp
fBTk_Free3DBorder(fIborderfB)fR
.SH ARGUMENTS
.AS "Tk_3DBorder" borderWidth
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Token for window (for all procedures except fBTk_Get3DBorderfR,
must be the window for which the border was allocated).
.AP Tcl_Obj *objPtr in
.VS 8.1
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.
.AP char *colorName in
Same as fIobjPtrfR except value is supplied as a string rather
than an object.
.VE
.AP Drawable drawable in
X token for window or pixmap;  indicates where graphics are to be drawn.
Must either be the X window for fItkwinfR or a pixmap with the
same screen and depth as fItkwinfR.
.AP Tk_3DBorder border in
Token for border previously allocated in call to fBTk_Get3DBorderfR.
.AP int x in
X-coordinate of upper-left corner of rectangle describing border
or bevel, in pixels.
.AP int y in
Y-coordinate of upper-left corner of rectangle describing border or
bevel, in pixels.
.AP int width in
Width of rectangle describing border or bevel, in pixels.
.AP int height in
Height of rectangle describing border or bevel, in pixels.
.AP int borderWidth in
Width of border in pixels. Positive means border is inside rectangle
given by fIxfR, fIyfR, fIwidthfR, fIheightfR, negative means
border is outside rectangle.
.AP 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 fBTk_Fill3DRectanglefR).
.AP 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).
.AP int numPoints in
Number of points at fI*pointPtrfR.
.AP int polyBorderWidth in
Width of border in pixels.  If positive, border is drawn to left of
trajectory given by fIpointPtrfR;  if negative, border is drawn to
right of trajectory.  If fIleftRelieffR is TK_RELIEF_GROOVE or
TK_RELIEF_RIDGE then the border is centered on the trajectory.
.AP 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 fBTk_Fill3DPolygonfR, TK_RELIEF_FLAT may also be specified to
indicate no difference in height.
.AP int leftBevel in
Non-zero means this bevel forms the left side of the object;  zero means
it forms the right side.
.AP 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.
.AP 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.
.AP int topBevel in
Non-zero means this bevel forms the top side of the object;  zero means
it forms the bottom side.
.AP 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.
.BE
.SH DESCRIPTION
.PP
These procedures provide facilities for drawing window borders in a
way that produces a three-dimensional appearance.
.VS 8.1
fBTk_Alloc3DBorderFromObjfR
allocates colors and Pixmaps needed to draw a border in the window
given by the fItkwinfR argument.  The value of fIobjPtrfR
is a standard Tk color name that determines the border colors.
The color indicated by fIobjPtrfR 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 fIobjPtrfR, and the shadowed portions of the border will appear
darker than fIobjPtrfR.
.PP
fBTk_Alloc3DBorderFromObjfR returns a token that may be used in later calls
to fBTk_Draw3DRectanglefR.  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 fIinterp->resultfR.
If it returns successfully, fBTk_Alloc3DBorderFromObjfR caches
information about the return value in fIobjPtrfR, which speeds up
future calls to fBTk_Alloc3DBorderFromObjfR with the same fIobjPtrfR
and fItkwinfR.
.PP
fBTk_Get3DBorderfR is identical to fBTk_Alloc3DBorderFromObjfR except
that the color is specified with a string instead of an object.  This
prevents fBTk_Get3DBorderfR from caching the return value, so
fBTk_Get3DBorderfR is less efficient than fBTk_Alloc3DBorderFromObjfR.
.PP
fBTk_Get3DBorderFromObjfR returns the token for an existing border, given
the window and color name used to create the border.
fBTk_Get3DBorderFromObjfR doesn't actually create the border; it must
already have been created with a previous call to
fBTk_Alloc3DBorderFromObjfR or fBTk_Get3DBorderfR.  The return
value is cached in fIobjPtrfR, which speeds up
future calls to fBTk_Get3DBorderFromObjfR with the same fIobjPtrfR
and fItkwinfR.
.VE
.PP
Once a border structure has been created, fBTk_Draw3DRectanglefR may be
invoked to draw the border.
The fItkwinfR argument specifies the
window for which the border was allocated, and fIdrawablefR
specifies a window or pixmap in which the border is to be drawn.
fIDrawablefR need not refer to the same window as fItkwinfR, but it
must refer to a compatible
pixmap or window:  one associated with the same screen and with the
same depth as fItkwinfR.
The fIxfR, fIyfR, fIwidthfR, and
fIheightfR arguments define the bounding box of the border region
within fIdrawablefR (usually fIxfR and fIyfR are zero and
fIwidthfR and fIheightfR are the dimensions of the window), and
fIborderWidthfR specifies the number of pixels actually
occupied by the border.  The fIrelieffR 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.
.PP
fBTk_Fill3DRectanglefR is somewhat like fBTk_Draw3DRectanglefR except
that it first fills the rectangular area with the background color
(one corresponding
to the color used to create fIborderfR).  Then it calls
fBTk_Draw3DRectanglefR to draw a border just inside the outer edge of
the rectangular area.  The argument fIrelieffR 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).
.PP
The procedure fBTk_Draw3DPolygonfR may be used to draw more complex
shapes with a three-dimensional appearance.  The fIpointPtrfR and
fInumPointsfR arguments define a trajectory, fIpolyBorderWidthfR
indicates how wide the border should be (and on which side of the
trajectory to draw it), and fIleftRelieffR indicates which side
of the trajectory should appear raised.  fBTk_Draw3DPolygonfR
draws a border around the given trajectory using the colors from
fIborderfR 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.
.PP
fBTk_Fill3DPolygonfR is to fBTk_Draw3DPolygonfR what
fBTk_Fill3DRectanglefR is to fBTk_Draw3DRectanglefR:  it fills
the polygonal area with the background color from fIborderfR,
then calls fBTk_Draw3DPolygonfR to draw a border around the
area (unless fIleftRelieffR is TK_RELIEF_FLAT;  in this case no
border is drawn).
.PP
The procedures fBTk_3DVerticalBevelfR and fBTk_3DHorizontalBevelfR
provide lower-level drawing primitives that are used by
procedures such as fBTk_Draw3DRectanglefR.
These procedures are also useful in their own right for drawing
rectilinear border shapes.
fBTk_3DVerticalBevelfR draws a vertical beveled edge, such as the
left or right side of a rectangle, and fBTk_3DHorizontalBevelfR
draws a horizontal beveled edge, such as the top or bottom of a
rectangle.
Each procedure takes fIxfR, fIyfR, fIwidthfR, and fIheightfR
arguments that describe the rectangular area of the beveled edge
(e.g., fIwidthfR is the border width for fBTk_3DVerticalBevelfR).
The fIleftBorderfR and fItopBorderfR arguments indicate the
position of the border relative to the ``inside'' of the object, and
fIrelieffR indicates the relief of the inside of the object relative
to the outside.
fBTk_3DVerticalBevelfR just draws a rectangular region.
fBTk_3DHorizontalBevelfR draws a trapezoidal region to generate
mitered corners;  it should be called after fBTk_3DVerticalBevelfR
(otherwise fBTk_3DVerticalBevelfR will overwrite the mitering in
the corner).
The fIleftInfR and fIrightInfR arguments to fBTk_3DHorizontalBevelfR
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 fIleftInfR and fIrightInfR, and the
bottom bevel should be drawn with 0 for both arguments.
.PP
The procedure fBTk_SetBackgroundFromBorderfR will modify the background
pixel and/or pixmap of fItkwinfR to produce a result compatible
with fIborderfR.  For color displays, the resulting background will
just be the color specified when fIborderfR 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.
.PP
Given a token for a border, the procedure fBTk_NameOf3DBorderfR
will return the color name that was used to create the border.
.PP
The procedure fBTk_3DBorderColorfR returns the XColor structure
that will be used for flat surfaces drawn for its fIborderfR
argument by procedures like fBTk_Fill3DRectanglefR.
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 fIborderfR exists.
.PP
The procedure fBTk_3DBorderGCfR returns one of the X graphics contexts
that are used to draw the border.
The argument fIwhichfR 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.
.PP
.VS 8.1
When a border is no longer needed, fBTk_Free3DBorderFromObjfR
or fBTk_Free3DBorderfR should
be called to release the resources associated with it.
For fBTk_Free3DBorderFromObjfR the border to release is specified
with the window and color name used to create the
border; for fBTk_Free3DBorderfR the border to release is specified
with the Tk_3DBorder token for the border.
There should be exactly one call to fBTk_Free3DBorderFromObjfR or
fBTk_Free3DBorderfR for each call to fBTk_Alloc3DBorderFromObjfR
or fBTk_Get3DBorderfR.
.VE
.SH KEYWORDS
3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect

						