1Tk_Alloc3DBorderFromObj(3) Tk Library Procedures Tk_Alloc3DBorderFromObj(3)
2______________________________________________________________________________
6
8 Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj,
9 Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon,
10 Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBack‐
11 groundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC,
12 Tk_Free3DBorderFromObj, Tk_Free3DBorder - draw borders with three-
13 dimensional appearance
14
16 #include <tk.h>
17 Tk_3DBorder
19 Tk_Alloc3DBorderFromObj(interp, tkwin, objPtr)
20 Tk_3DBorder
22 Tk_Get3DBorder(interp, tkwin, colorName)
23 Tk_3DBorder
25 Tk_Get3DBorderFromObj(tkwin, objPtr)
26 void
28 Tk_Draw3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)
29 void
31 Tk_Fill3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)
32 void
34 Tk_Draw3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)
35 void
37 Tk_Fill3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)
38 void
40 Tk_3DVerticalBevel(tkwin, drawable, border, x, y, width, height, leftBevel, relief)
41 void
43 Tk_3DHorizontalBevel(tkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief)
44 void
46 Tk_SetBackgroundFromBorder(tkwin, border)
47 const char *
49 Tk_NameOf3DBorder(border)
50 XColor *
52 Tk_3DBorderColor(border)
53 GC *
55 Tk_3DBorderGC(tkwin, border, which)
56 Tk_Free3DBorderFromObj(tkwin, objPtr)
58 Tk_Free3DBorder(border)
60
62 Tcl_Interp *interp (in) Interpreter to use for error
63 reporting.
64 Tk_Window tkwin (in) Token for window (for all proce‐
66 dures except Tk_Get3DBorder, must
67 be the window for which the bor‐
68 der was allocated).
69 Tcl_Obj *objPtr (in) Pointer to object whose value
71 describes color corresponding to
72 background (flat areas). Illumi‐
73 nated edges will be brighter than
74 this and shadowed edges will be
75 darker than this.
76 char *colorName (in) Same as objPtr except value is
78 supplied as a string rather than
79 an object.
80 Drawable drawable (in) X token for window or pixmap;
82 indicates where graphics are to
83 be drawn. Must either be the X
84 window for tkwin or a pixmap with
85 the same screen and depth as
86 tkwin.
87 Tk_3DBorder border (in) Token for border previously allo‐
89 cated in call to Tk_Get3DBorder.
90 int x (in) X-coordinate of upper-left corner
92 of rectangle describing border or
93 bevel, in pixels.
94 int y (in) Y-coordinate of upper-left corner
96 of rectangle describing border or
97 bevel, in pixels.
98 int width (in) Width of rectangle describing
100 border or bevel, in pixels.
101 int height (in) Height of rectangle describing
103 border or bevel, in pixels.
104 int borderWidth (in) Width of border in pixels. Posi‐
106 tive means border is inside rec‐
107 tangle given by x, y, width,
108 height, negative means border is
109 outside rectangle.
110 int relief (in) Indicates 3-D position of inte‐
112 rior of object relative to exte‐
113 rior; should be TK_RELIEF_RAISED,
114 TK_RELIEF_SUNKEN,
115 TK_RELIEF_GROOVE,
116 TK_RELIEF_SOLID, or
117 TK_RELIEF_RIDGE (may also be
118 TK_RELIEF_FLAT for Tk_Fill3DRect‐
119 angle).
120 XPoint *pointPtr (in) Pointer to array of points
122 describing the set of vertices in
123 a polygon. The polygon need not
124 be closed (it will be closed
125 automatically if it is not).
126 int numPoints (in) Number of points at *pointPtr.
128 int polyBorderWidth (in) Width of border in pixels. If
130 positive, border is drawn to left
131 of trajectory given by pointPtr;
132 if negative, border is drawn to
133 right of trajectory. If leftRe‐
134 lief is TK_RELIEF_GROOVE or
135 TK_RELIEF_RIDGE then the border
136 is centered on the trajectory.
137 int leftRelief (in) Height of left side of polygon's
139 path relative to right.
140 TK_RELIEF_RAISED means left side
141 should appear higher and
142 TK_RELIEF_SUNKEN means right side
143 should appear higher;
144 TK_RELIEF_GROOVE and
145 TK_RELIEF_RIDGE mean the obvious
146 things. For Tk_Fill3DPolygon,
147 TK_RELIEF_FLAT may also be speci‐
148 fied to indicate no difference in
149 height.
150 int leftBevel (in) Non-zero means this bevel forms
152 the left side of the object;
153 zero means it forms the right
154 side.
155 int leftIn (in) Non-zero means that the left edge
157 of the horizontal bevel angles
158 in, so that the bottom of the
159 edge is farther to the right than
160 the top. Zero means the edge
161 angles out, so that the bottom is
162 farther to the left than the top.
163 int rightIn (in) Non-zero means that the right
165 edge of the horizontal bevel
166 angles in, so that the bottom of
167 the edge is farther to the left
168 than the top. Zero means the
169 edge angles out, so that the bot‐
170 tom is farther to the right than
171 the top.
172 int topBevel (in) Non-zero means this bevel forms
174 the top side of the object; zero
175 means it forms the bottom side.
176 int which (in) Specifies which of the border's
178 graphics contexts is desired.
179 Must be TK_3D_FLAT_GC,
180 TK_3D_LIGHT_GC, or TK_3D_DARK_GC.
181_________________________________________________________________
182
185 These procedures provide facilities for drawing window borders in a way
186 that produces a three-dimensional appearance. Tk_Alloc3DBorderFromObj
187 allocates colors and Pixmaps needed to draw a border in the window
188 given by the tkwin argument. The value of objPtr is a standard Tk
189 color name that determines the border colors. The color indicated by
190 objPtr will not actually be used in the border; it indicates the back‐
191 ground color for the window (i.e. a color for flat surfaces). The
192 illuminated portions of the border will appear brighter than indicated
193 by objPtr, and the shadowed portions of the border will appear darker
194 than objPtr.
195 Tk_Alloc3DBorderFromObj returns a token that may be used in later calls
197 to Tk_Draw3DRectangle. If an error occurs in allocating information
198 for the border (e.g. a bogus color name was given) then NULL is
199 returned and an error message is left in interp->result. If it returns
200 successfully, Tk_Alloc3DBorderFromObj caches information about the
201 return value in objPtr, which speeds up future calls to Tk_Alloc3DBor‐
202 derFromObj with the same objPtr and tkwin.
203 Tk_Get3DBorder is identical to Tk_Alloc3DBorderFromObj except that the
205 color is specified with a string instead of an object. This prevents
206 Tk_Get3DBorder from caching the return value, so Tk_Get3DBorder is less
207 efficient than Tk_Alloc3DBorderFromObj.
208 Tk_Get3DBorderFromObj returns the token for an existing border, given
210 the window and color name used to create the border. Tk_Get3DBorder‐
211 FromObj does not actually create the border; it must already have been
212 created with a previous call to Tk_Alloc3DBorderFromObj or Tk_Get3DBor‐
213 der. The return value is cached in objPtr, which speeds up future
214 calls to Tk_Get3DBorderFromObj with the same objPtr and tkwin.
215 Once a border structure has been created, Tk_Draw3DRectangle may be
217 invoked to draw the border. The tkwin argument specifies the window
218 for which the border was allocated, and drawable specifies a window or
219 pixmap in which the border is to be drawn. Drawable need not refer to
220 the same window as tkwin, but it must refer to a compatible pixmap or
221 window: one associated with the same screen and with the same depth as
222 tkwin. The x, y, width, and height arguments define the bounding box
223 of the border region within drawable (usually x and y are zero and
224 width and height are the dimensions of the window), and borderWidth
225 specifies the number of pixels actually occupied by the border. The
226 relief argument indicates which of several three-dimensional effects is
227 desired: TK_RELIEF_RAISED means that the interior of the rectangle
228 should appear raised relative to the exterior of the rectangle, and
229 TK_RELIEF_SUNKEN means that the interior should appear depressed.
230 TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to
231 be a groove or ridge around the exterior of the rectangle.
232 Tk_Fill3DRectangle is somewhat like Tk_Draw3DRectangle except that it
234 first fills the rectangular area with the background color (one corre‐
235 sponding to the color used to create border). Then it calls
236 Tk_Draw3DRectangle to draw a border just inside the outer edge of the
237 rectangular area. The argument relief indicates the desired effect
238 (TK_RELIEF_FLAT means no border should be drawn; all that happens is to
239 fill the rectangle with the background color).
240 The procedure Tk_Draw3DPolygon may be used to draw more complex shapes
242 with a three-dimensional appearance. The pointPtr and numPoints argu‐
243 ments define a trajectory, polyBorderWidth indicates how wide the bor‐
244 der should be (and on which side of the trajectory to draw it), and
245 leftRelief indicates which side of the trajectory should appear raised.
246 Tk_Draw3DPolygon draws a border around the given trajectory using the
247 colors from border to produce a three-dimensional appearance. If the
248 trajectory is non-self-intersecting, the appearance will be a raised or
249 sunken polygon shape. The trajectory may be self-intersecting,
250 although it's not clear how useful this is.
251 Tk_Fill3DPolygon is to Tk_Draw3DPolygon what Tk_Fill3DRectangle is to
253 Tk_Draw3DRectangle: it fills the polygonal area with the background
254 color from border, then calls Tk_Draw3DPolygon to draw a border around
255 the area (unless leftRelief is TK_RELIEF_FLAT; in this case no border
256 is drawn).
257 The procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel provide
259 lower-level drawing primitives that are used by procedures such as
260 Tk_Draw3DRectangle. These procedures are also useful in their own
261 right for drawing rectilinear border shapes. Tk_3DVerticalBevel draws
262 a vertical beveled edge, such as the left or right side of a rectangle,
263 and Tk_3DHorizontalBevel draws a horizontal beveled edge, such as the
264 top or bottom of a rectangle. Each procedure takes x, y, width, and
265 height arguments that describe the rectangular area of the beveled edge
266 (e.g., width is the border width for Tk_3DVerticalBevel). The leftBor‐
267 der and topBorder arguments indicate the position of the border rela‐
268 tive to the “inside” of the object, and relief indicates the relief of
269 the inside of the object relative to the outside. Tk_3DVerticalBevel
270 just draws a rectangular region. Tk_3DHorizontalBevel draws a trape‐
271 zoidal region to generate mitered corners; it should be called after
272 Tk_3DVerticalBevel (otherwise Tk_3DVerticalBevel will overwrite the
273 mitering in the corner). The leftIn and rightIn arguments to Tk_3DHor‐
274 izontalBevel describe the mitering at the corners; a value of 1 means
275 that the bottom edge of the trapezoid will be shorter than the top, 0
276 means it will be longer. For example, to draw a rectangular border the
277 top bevel should be drawn with 1 for both leftIn and rightIn, and the
278 bottom bevel should be drawn with 0 for both arguments.
279 The procedure Tk_SetBackgroundFromBorder will modify the background
281 pixel and/or pixmap of tkwin to produce a result compatible with bor‐
282 der. For color displays, the resulting background will just be the
283 color specified when border was created; for monochrome displays, the
284 resulting background will be a light stipple pattern, in order to dis‐
285 tinguish the background from the illuminated portion of the border.
286 Given a token for a border, the procedure Tk_NameOf3DBorder will return
288 the color name that was used to create the border.
289 The procedure Tk_3DBorderColor returns the XColor structure that will
291 be used for flat surfaces drawn for its border argument by procedures
292 like Tk_Fill3DRectangle. The return value corresponds to the color
293 name that was used to create the border. The XColor, and its associ‐
294 ated pixel value, will remain allocated as long as border exists.
295 The procedure Tk_3DBorderGC returns one of the X graphics contexts that
297 are used to draw the border. The argument which selects which one of
298 the three possible GC's: TK_3D_FLAT_GC returns the context used for
299 flat surfaces, TK_3D_LIGHT_GC returns the context for light shadows,
300 and TK_3D_DARK_GC returns the context for dark shadows.
301 When a border is no longer needed, Tk_Free3DBorderFromObj or
303 Tk_Free3DBorder should be called to release the resources associated
304 with it. For Tk_Free3DBorderFromObj the border to release is specified
305 with the window and color name used to create the border; for
306 Tk_Free3DBorder the border to release is specified with the Tk_3DBorder
307 token for the border. There should be exactly one call to
308 Tk_Free3DBorderFromObj or Tk_Free3DBorder for each call to
309 Tk_Alloc3DBorderFromObj or Tk_Get3DBorder.
310
313 3D, background, border, color, depressed, illumination, object, poly‐
314 gon, raised, shadow, three-dimensional effect
315Tk 8.1 Tk_Alloc3DBorderFromObj(3)