tk/doc/3DBorder.3

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