1# Copyright (c) 1990-1993 The Regents of the University of California. 2# Copyright (c) 1994-1996 Sun Microsystems, Inc. 3# See the file "license.terms" for information on usage and redistribution 4# of this file, and for a DISCLAIMER OF ALL WARRANTIES. 5# 6# 7 8=head1 NAME 9 10Tk_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 11 12=for category C Programming 13 14=head1 SYNOPSIS 15 16B<#include E<lt>tk.hE<gt>> 17 18Tk_3DBorder 19B<Tk_Get3DBorder(>I<interp, tkwin, colorName>B<)> 20 21void 22B<Tk_Draw3DRectangle(>I<tkwin, drawable, border, x, y, width, height, borderWidth, relief>B<)> 23 24void 25B<Tk_Fill3DRectangle(>I<tkwin, drawable, border, x, y, width, height, borderWidth, relief>B<)> 26 27void 28B<Tk_Draw3DPolygon(>I<tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief>B<)> 29 30void 31B<Tk_Fill3DPolygon(>I<tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief>B<)> 32 33void 34B<Tk_3DVerticalBevel>(I<tkwin, drawable, border, x, y, width, height, leftBevel, relief>B<)> 35 36void 37B<Tk_3DHorizontalBevel>(I<tkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief>B<)> 38 39void 40B<Tk_SetBackgroundFromBorder(>I<tkwin, border>B<)> 41 42char * 43B<Tk_NameOf3DBorder(>I<border>B<)> 44 45XColor * 46B<Tk_3DBorderColor(>I<border>B<)> 47 48GC * 49B<Tk_3DBorderGC(>I<tkwin, border, which>B<)> 50 51B<Tk_Free3DBorder(>I<border>B<)> 52 53=head1 ARGUMENTS 54 55=over 4 56 57=item Tcl_Interp *interp (in) 58 59Interpreter to use for error reporting. 60 61=item Tk_Window tkwin (in) 62 63Token for window (for all procedures except B<Tk_Get3DBorder>, 64must be the window for which the border was allocated). 65 66=item Tk_Uid colorName (in) 67 68Textual description of color corresponding to background (flat areas). 69Illuminated edges will be brighter than this and shadowed edges will 70be darker than this. 71 72=item Drawable drawable (in) 73 74X token for window or pixmap; indicates where graphics are to be drawn. 75Must either be the X window for I<tkwin> or a pixmap with the 76same screen and depth as I<tkwin>. 77 78=item Tk_3DBorder border (in) 79 80Token for border previously allocated in call to B<Tk_Get3DBorder>. 81 82=item int x (in) 83 84X-coordinate of upper-left corner of rectangle describing border 85or bevel, in pixels. 86 87=item int y (in) 88 89Y-coordinate of upper-left corner of rectangle describing border or 90bevel, in pixels. 91 92=item int width (in) 93 94Width of rectangle describing border or bevel, in pixels. 95 96=item int height (in) 97 98Height of rectangle describing border or bevel, in pixels. 99 100=item int borderWidth (in) 101 102Width of border in pixels. Positive means border is inside rectangle 103given by I<x>, I<y>, I<width>, I<height>, negative means 104border is outside rectangle. 105 106=item int relief (in) 107 108Indicates 3-D position of interior of object relative to exterior; 109should be TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, 110TK_RELIEF_SOLID, or TK_RELIEF_RIDGE (may also be TK_RELIEF_FLAT 111for B<Tk_Fill3DRectangle>). 112 113=item XPoint *pointPtr (in) 114 115Pointer to array of points describing the set of vertices in a polygon. 116The polygon need not be closed (it will be closed automatically if it 117isn't). 118 119=item int numPoints (in) 120 121Number of points at I<*pointPtr>. 122 123=item int polyBorderWidth (in) 124 125Width of border in pixels. If positive, border is drawn to left of 126trajectory given by I<pointPtr>; if negative, border is drawn to 127right of trajectory. If I<leftRelief> is TK_RELIEF_GROOVE or 128TK_RELIEF_RIDGE then the border is centered on the trajectory. 129 130=item int leftRelief (in) 131 132Height of left side of polygon's path relative to right. TK_RELIEF_RAISED 133means left side should appear higher and TK_RELIEF_SUNKEN means right side 134should appear higher; 135TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things. 136For B<Tk_Fill3DPolygon>, TK_RELIEF_FLAT may also be specified to 137indicate no difference in height. 138 139=item int leftBevel (in) 140 141Non-zero means this bevel forms the left side of the object; zero means 142it forms the right side. 143 144=item int leftIn (in) 145 146Non-zero means that the left edge of the horizontal bevel angles in, 147so that the bottom of the edge is farther to the right than 148the top. 149Zero means the edge angles out, so that the bottom is farther to the 150left than the top. 151 152=item int rightIn (in) 153 154Non-zero means that the right edge of the horizontal bevel angles in, 155so that the bottom of the edge is farther to the left than the top. 156Zero means the edge angles out, so that the bottom is farther to the 157right than the top. 158 159=item int topBevel (in) 160 161Non-zero means this bevel forms the top side of the object; zero means 162it forms the bottom side. 163 164=item int which (in) 165 166Specifies which of the border's graphics contexts is desired. 167Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC. 168 169=back 170 171=head1 DESCRIPTION 172 173These procedures provide facilities for drawing window borders in a 174way that produces a three-dimensional appearance. B<Tk_Get3DBorder> 175allocates colors and Pixmaps needed to draw a border in the window 176given by the I<tkwin> argument. The I<colorName> 177argument indicates what colors should be used in the border. 178I<ColorName> may be any value acceptable to B<Tk_GetColor>. 179The color indicated by I<colorName> will not actually be used in 180the border; it indicates the background color for the window 181(i.e. a color for flat surfaces). 182The illuminated portions of the border will appear brighter than indicated 183by I<colorName>, and the shadowed portions of the border will appear 184darker than I<colorName>. 185 186B<Tk_Get3DBorder> returns a token that may be used in later calls 187to B<Tk_Draw3DRectangle>. If an error occurs in allocating information 188for the border (e.g. I<colorName> isn't a legal color specifier), 189then NULL is returned and an error message is left in I<interp-E<gt>result>. 190 191Once a border structure has been created, B<Tk_Draw3DRectangle> may be 192invoked to draw the border. 193The I<tkwin> argument specifies the 194window for which the border was allocated, and I<drawable> 195specifies a window or pixmap in which the border is to be drawn. 196I<Drawable> need not refer to the same window as I<tkwin>, but it 197must refer to a compatible 198pixmap or window: one associated with the same screen and with the 199same depth as I<tkwin>. 200The I<x>, I<y>, I<width>, and 201I<height> arguments define the bounding box of the border region 202within I<drawable> (usually I<x> and I<y> are zero and 203I<width> and I<height> are the dimensions of the window), and 204I<borderWidth> specifies the number of pixels actually 205occupied by the border. The I<relief> argument indicates 206which of several three-dimensional effects is desired: 207TK_RELIEF_RAISED means that the interior of the rectangle should appear raised 208relative to the exterior of the rectangle, and 209TK_RELIEF_SUNKEN means that the interior should appear depressed. 210TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to be 211a groove or ridge around the exterior of the rectangle. 212 213B<Tk_Fill3DRectangle> is somewhat like B<Tk_Draw3DRectangle> except 214that it first fills the rectangular area with the background color 215(one corresponding 216to the I<colorName> used to create I<border>). Then it calls 217B<Tk_Draw3DRectangle> to draw a border just inside the outer edge of 218the rectangular area. The argument I<relief> indicates the desired 219effect (TK_RELIEF_FLAT means no border should be drawn; all that 220happens is to fill the rectangle with the background color). 221 222The procedure B<Tk_Draw3DPolygon> may be used to draw more complex 223shapes with a three-dimensional appearance. The I<pointPtr> and 224I<numPoints> arguments define a trajectory, I<polyBorderWidth> 225indicates how wide the border should be (and on which side of the 226trajectory to draw it), and I<leftRelief> indicates which side 227of the trajectory should appear raised. B<Tk_Draw3DPolygon> 228draws a border around the given trajectory using the colors from 229I<border> to produce a three-dimensional appearance. If the trajectory is 230non-self-intersecting, the appearance will be a raised or sunken 231polygon shape. The trajectory may be self-intersecting, although 232it's not clear how useful this is. 233 234B<Tk_Fill3DPolygon> is to B<Tk_Draw3DPolygon> what 235B<Tk_Fill3DRectangle> is to B<Tk_Draw3DRectangle>: it fills 236the polygonal area with the background color from I<border>, 237then calls B<Tk_Draw3DPolygon> to draw a border around the 238area (unless I<leftRelief> is TK_RELIEF_FLAT; in this case no 239border is drawn). 240 241The procedures B<Tk_3DVerticalBevel> and B<Tk_3DHorizontalBevel> 242provide lower-level drawing primitives that are used by 243procedures such as B<Tk_Draw3DRectangle>. 244These procedures are also useful in their own right for drawing 245rectilinear border shapes. 246B<Tk_3DVerticalBevel> draws a vertical beveled edge, such as the 247left or right side of a rectangle, and B<Tk_3DHorizontalBevel> 248draws a horizontal beveled edge, such as the top or bottom of a 249rectangle. 250Each procedure takes I<x>, I<y>, I<width>, and I<height> 251arguments that describe the rectangular area of the beveled edge 252(e.g., I<width> is the border width for B<Tk_3DVerticalBevel>). 253The I<leftBorder> and I<topBorder> arguments indicate the 254position of the border relative to the ``inside'' of the object, and 255I<relief> indicates the relief of the inside of the object relative 256to the outside. 257B<Tk_3DVerticalBevel> just draws a rectangular region. 258B<Tk_3DHorizontalBevel> draws a trapezoidal region to generate 259mitered corners; it should be called after B<Tk_3DVerticalBevel> 260(otherwise B<Tk_3DVerticalBevel> will overwrite the mitering in 261the corner). 262The I<leftIn> and I<rightIn> arguments to B<Tk_3DHorizontalBevel> 263describe the mitering at the corners; a value of 1 means that the bottom 264edge of the trapezoid will be shorter than the top, 0 means it will 265be longer. 266For example, to draw a rectangular border the top bevel should be 267drawn with 1 for both I<leftIn> and I<rightIn>, and the 268bottom bevel should be drawn with 0 for both arguments. 269 270The procedure B<Tk_SetBackgroundFromBorder> will modify the background 271pixel and/or pixmap of I<tkwin> to produce a result compatible 272with I<border>. For color displays, the resulting background will 273just be the color given by the I<colorName> argument passed to 274B<Tk_Get3DBorder> when I<border> was created; for monochrome 275displays, the resulting background 276will be a light stipple pattern, in order to distinguish the background from 277the illuminated portion of the border. 278 279Given a token for a border, the procedure B<Tk_NameOf3DBorder> 280will return the I<colorName> string that was passed to 281B<Tk_Get3DBorder> to create the border. 282 283The procedure B<Tk_3DBorderColor> returns the XColor structure 284that will be used for flat surfaces drawn for its I<border> 285argument by procedures like B<Tk_Fill3DRectangle>. 286The return value corresponds to the I<colorName> passed to 287B<Tk_Get3DBorder>. 288The XColor, and its associated pixel value, will remain allocated 289as long as I<border> exists. 290 291The procedure B<Tk_3DBorderGC> returns one of the X graphics contexts 292that are used to draw the border. 293The argument I<which> selects which one of the three possible GC's: 294TK_3D_FLAT_GC returns the context used for flat surfaces, 295TK_3D_LIGHT_GC returns the context for light shadows, 296and TK_3D_DARK_GC returns the context for dark shadows. 297 298When a border is no longer needed, B<Tk_Free3DBorder> should 299be called to release the resources associated with the border. 300There should be exactly one call to B<Tk_Free3DBorder> for 301each call to B<Tk_Get3DBorder>. 302 303=head1 KEYWORDS 304 3053D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect 306