'\"'\" Copyright (c) 1990-1993 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.'\" '\" SCCS: @(#) 3DBorder.3 1.23 96/11/17 15:03:05'\" .so man.macros.TH Tk_Get3DBorder 3 4.0 Tk "Tk Library Procedures".BS.SH NAMETk_Get3DBorder, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorder \- draw borders with three-dimensional appearance.SH SYNOPSIS.nf\fB#include <tk.h>\fR.spTk_3DBorder\fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR.spvoid\fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR.spvoid\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR.spvoid\fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR.spvoid\fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR.spvoid\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR.spvoid\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR.spvoid\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR.spchar *\fBTk_NameOf3DBorder(\fIborder\fB)\fR.spXColor *\fBTk_3DBorderColor(\fIborder\fB)\fR.spGC *\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR.sp\fBTk_Free3DBorder(\fIborder\fB)\fR.SH ARGUMENTS.AS "Tk_3DBorder" borderWidth.AP Tcl_Interp *interp inInterpreter to use for error reporting..AP Tk_Window tkwin inToken for window (for all procedures except \fBTk_Get3DBorder\fR,must be the window for which the border was allocated)..AP Tk_Uid colorName inTextual description of color corresponding to background (flat areas).Illuminated edges will be brighter than this and shadowed edges willbe darker than this..AP Drawable drawable inX token for window or pixmap;  indicates where graphics are to be drawn.Must either be the X window for \fItkwin\fR or a pixmap with thesame screen and depth as \fItkwin\fR..AP Tk_3DBorder border inToken for border previously allocated in call to \fBTk_Get3DBorder\fR..AP int x inX-coordinate of upper-left corner of rectangle describing borderor bevel, in pixels..AP int y inY-coordinate of upper-left corner of rectangle describing border orbevel, in pixels..AP int width inWidth of rectangle describing border or bevel, in pixels..AP int height inHeight of rectangle describing border or bevel, in pixels..AP int borderWidth inWidth of border in pixels. Positive means border is inside rectanglegiven by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative meansborder is outside rectangle..AP int relief inIndicates 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_FLATfor \fBTk_Fill3DRectangle\fR)..AP XPoint *pointPtr inPointer to array of points describing the set of vertices in a polygon.The polygon need not be closed (it will be closed automatically if itisn't)..AP int numPoints inNumber of points at \fI*pointPtr\fR..AP int polyBorderWidth inWidth of border in pixels.  If positive, border is drawn to left oftrajectory given by \fIpointPtr\fR;  if negative, border is drawn toright of trajectory.  If \fIleftRelief\fR is TK_RELIEF_GROOVE orTK_RELIEF_RIDGE then the border is centered on the trajectory..AP int leftRelief inHeight of left side of polygon's path relative to right.  TK_RELIEF_RAISEDmeans left side should appear higher and TK_RELIEF_SUNKEN means right sideshould appear higher;TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things.For \fBTk_Fill3DPolygon\fR, TK_RELIEF_FLAT may also be specified toindicate no difference in height..AP int leftBevel inNon-zero means this bevel forms the left side of the object;  zero meansit forms the right side..AP int leftIn inNon-zero means that the left edge of the horizontal bevel angles in,so that the bottom of the edge is farther to the right thanthe top.Zero means the edge angles out, so that the bottom is farther to theleft than the top..AP int rightIn inNon-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 theright than the top..AP int topBevel inNon-zero means this bevel forms the top side of the object;  zero meansit forms the bottom side..AP int which inSpecifies 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.PPThese procedures provide facilities for drawing window borders in away that produces a three-dimensional appearance.  \fBTk_Get3DBorder\fRallocates colors and Pixmaps needed to draw a border in the windowgiven by the \fItkwin\fR argument.  The \fIcolorName\fRargument indicates what colors should be used in the border.\fIColorName\fR may be any value acceptable to \fBTk_GetColor\fR.The color indicated by \fIcolorName\fR will not actually be used inthe 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 indicatedby \fIcolorName\fR, and the shadowed portions of the border will appeardarker than \fIcolorName\fR..PP\fBTk_Get3DBorder\fR returns a token that may be used in later callsto \fBTk_Draw3DRectangle\fR.  If an error occurs in allocating informationfor the border (e.g. \fIcolorName\fR isn't a legal color specifier),then NULL is returned and an error message is left in \fIinterp->result\fR..PPOnce a border structure has been created, \fBTk_Draw3DRectangle\fR may beinvoked to draw the border.The \fItkwin\fR argument specifies thewindow for which the border was allocated, and \fIdrawable\fRspecifies a window or pixmap in which the border is to be drawn.\fIDrawable\fR need not refer to the same window as \fItkwin\fR, but itmust refer to a compatiblepixmap or window:  one associated with the same screen and with thesame depth as \fItkwin\fR.The \fIx\fR, \fIy\fR, \fIwidth\fR, and\fIheight\fR arguments define the bounding box of the border regionwithin \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and\fIwidth\fR and \fIheight\fR are the dimensions of the window), and\fIborderWidth\fR specifies the number of pixels actuallyoccupied by the border.  The \fIrelief\fR argument indicateswhich of several three-dimensional effects is desired:TK_RELIEF_RAISED means that the interior of the rectangle should appear raisedrelative to the exterior of the rectangle, andTK_RELIEF_SUNKEN means that the interior should appear depressed.TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to bea groove or ridge around the exterior of the rectangle..PP\fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR exceptthat it first fills the rectangular area with the background color(one correspondingto the \fIcolorName\fR used to create \fIborder\fR).  Then it calls\fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge ofthe rectangular area.  The argument \fIrelief\fR indicates the desiredeffect (TK_RELIEF_FLAT means no border should be drawn; all thathappens is to fill the rectangle with the background color)..PPThe procedure \fBTk_Draw3DPolygon\fR may be used to draw more complexshapes with a three-dimensional appearance.  The \fIpointPtr\fR and\fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fRindicates how wide the border should be (and on which side of thetrajectory to draw it), and \fIleftRelief\fR indicates which sideof the trajectory should appear raised.  \fBTk_Draw3DPolygon\fRdraws a border around the given trajectory using the colors from\fIborder\fR to produce a three-dimensional appearance.  If the trajectory isnon-self-intersecting, the appearance will be a raised or sunkenpolygon shape.  The trajectory may be self-intersecting, althoughit's not clear how useful this is..PP\fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what\fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR:  it fillsthe polygonal area with the background color from \fIborder\fR,then calls \fBTk_Draw3DPolygon\fR to draw a border around thearea (unless \fIleftRelief\fR is TK_RELIEF_FLAT;  in this case noborder is drawn)..PPThe procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fRprovide lower-level drawing primitives that are used byprocedures such as \fBTk_Draw3DRectangle\fR.These procedures are also useful in their own right for drawingrectilinear border shapes.\fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as theleft or right side of a rectangle, and \fBTk_3DHorizontalBevel\fRdraws a horizontal beveled edge, such as the top or bottom of arectangle.Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fRarguments that describe the rectangular area of the beveled edge(e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR).The \fIleftBorder\fR and \fItopBorder\fR arguments indicate theposition of the border relative to the ``inside'' of the object, and\fIrelief\fR indicates the relief of the inside of the object relativeto the outside.\fBTk_3DVerticalBevel\fR just draws a rectangular region.\fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generatemitered corners;  it should be called after \fBTk_3DVerticalBevel\fR(otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering inthe corner).The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fRdescribe the mitering at the corners;  a value of 1 means that the bottomedge of the trapezoid will be shorter than the top, 0 means it willbe longer.For example, to draw a rectangular border the top bevel should bedrawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and thebottom bevel should be drawn with 0 for both arguments..PPThe procedure \fBTk_SetBackgroundFromBorder\fR will modify the backgroundpixel and/or pixmap of \fItkwin\fR to produce a result compatiblewith \fIborder\fR.  For color displays, the resulting background willjust be the color given by the \fIcolorName\fR argument passed to\fBTk_Get3DBorder\fR when \fIborder\fR was created;  for monochromedisplays, the resulting backgroundwill be a light stipple pattern, in order to distinguish the background fromthe illuminated portion of the border..PPGiven a token for a border, the procedure \fBTk_NameOf3DBorder\fRwill return the \fIcolorName\fR string that was passed to\fBTk_Get3DBorder\fR to create the border..PPThe procedure \fBTk_3DBorderColor\fR returns the XColor structurethat will be used for flat surfaces drawn for its \fIborder\fRargument by procedures like \fBTk_Fill3DRectangle\fR.The return value corresponds to the \fIcolorName\fR passed to\fBTk_Get3DBorder\fR.The XColor, and its associated pixel value, will remain allocatedas long as \fIborder\fR exists..PPThe procedure \fBTk_3DBorderGC\fR returns one of the X graphics contextsthat are used to draw the border.The argument \fIwhich\fR 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..PPWhen a border is no longer needed, \fBTk_Free3DBorder\fR shouldbe called to release the resources associated with the border.There should be exactly one call to \fBTk_Free3DBorder\fR foreach call to \fBTk_Get3DBorder\fR..SH KEYWORDS3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect