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) │
78 Same as objPtr except value is │
79 supplied as a string rather than │
80 an object.
81 Drawable drawable (in) X token for window or pixmap;
83 indicates where graphics are to
84 be drawn. Must either be the X
85 window for tkwin or a pixmap with
86 the same screen and depth as
87 tkwin.
88 Tk_3DBorder border (in) Token for border previously allo‐
90 cated in call to Tk_Get3DBorder.
91 int x (in) X-coordinate of upper-left corner
93 of rectangle describing border or
94 bevel, in pixels.
95 int y (in) Y-coordinate of upper-left corner
97 of rectangle describing border or
98 bevel, in pixels.
99 int width (in) Width of rectangle describing
101 border or bevel, in pixels.
102 int height (in) Height of rectangle describing
104 border or bevel, in pixels.
105 int borderWidth (in) Width of border in pixels. Posi‐
107 tive means border is inside rec‐
108 tangle given by x, y, width,
109 height, negative means border is
110 outside rectangle.
111 int relief (in) Indicates 3-D position of inte‐
113 rior of object relative to exte‐
114 rior; should be TK_RELIEF_RAISED,
115 TK_RELIEF_SUNKEN,
116 TK_RELIEF_GROOVE,
117 TK_RELIEF_SOLID, or
118 TK_RELIEF_RIDGE (may also be
119 TK_RELIEF_FLAT for Tk_Fill3DRect‐
120 angle).
121 XPoint *pointPtr (in) Pointer to array of points
123 describing the set of vertices in
124 a polygon. The polygon need not
125 be closed (it will be closed
126 automatically if it isn't).
127 int numPoints (in) Number of points at *pointPtr.
129 int polyBorderWidth(in) Width of border in pixels. If
131 positive, border is drawn to left
132 of trajectory given by pointPtr;
133 if negative, border is drawn to
134 right of trajectory. If leftRe‐
135 lief is TK_RELIEF_GROOVE or
136 TK_RELIEF_RIDGE then the border
137 is centered on the trajectory.
138 int leftRelief (in) Height of left side of polygon's
140 path relative to right.
141 TK_RELIEF_RAISED means left side
142 should appear higher and
143 TK_RELIEF_SUNKEN means right side
144 should appear higher;
145 TK_RELIEF_GROOVE and
146 TK_RELIEF_RIDGE mean the obvious
147 things. For Tk_Fill3DPolygon,
148 TK_RELIEF_FLAT may also be speci‐
149 fied to indicate no difference in
150 height.
151 int leftBevel (in) Non-zero means this bevel forms
153 the left side of the object;
154 zero means it forms the right
155 side.
156 int leftIn (in) Non-zero means that the left edge
158 of the horizontal bevel angles
159 in, so that the bottom of the
160 edge is farther to the right than
161 the top. Zero means the edge
162 angles out, so that the bottom is
163 farther to the left than the top.
164 int rightIn (in) Non-zero means that the right
166 edge of the horizontal bevel
167 angles in, so that the bottom of
168 the edge is farther to the left
169 than the top. Zero means the
170 edge angles out, so that the bot‐
171 tom is farther to the right than
172 the top.
173 int topBevel (in) Non-zero means this bevel forms
175 the top side of the object; zero
176 means it forms the bottom side.
177 int which (in) Specifies which of the border's
179 graphics contexts is desired.
180 Must be TK_3D_FLAT_GC,
181 TK_3D_LIGHT_GC, or TK_3D_DARK_GC.
182_________________________________________________________________
183
186 These procedures provide facilities for drawing window borders in a way
187 that produces a three-dimensional appearance. Tk_Alloc3DBorderFromObj │
188 allocates colors and Pixmaps needed to draw a border in the window │
189 given by the tkwin argument. The value of objPtr is a standard Tk │
190 color name that determines the border colors. The color indicated by │
191 objPtr will not actually be used in the border; it indicates the back‐ │
192 ground color for the window (i.e. a color for flat surfaces). The │
193 illuminated portions of the border will appear brighter than indicated │
194 by objPtr, and the shadowed portions of the border will appear darker │
195 than objPtr. │
196 Tk_Alloc3DBorderFromObj returns a token that may be used in later calls │
198 to Tk_Draw3DRectangle. If an error occurs in allocating information │
199 for the border (e.g. a bogus color name was given) then NULL is │
200 returned and an error message is left in interp->result. If it returns │
201 successfully, Tk_Alloc3DBorderFromObj caches information about the │
202 return value in objPtr, which speeds up future calls to Tk_Alloc3DBor‐ │
203 derFromObj with the same objPtr and tkwin. │
204 Tk_Get3DBorder is identical to Tk_Alloc3DBorderFromObj except that the │
206 color is specified with a string instead of an object. This prevents │
207 Tk_Get3DBorder from caching the return value, so Tk_Get3DBorder is less │
208 efficient than Tk_Alloc3DBorderFromObj. │
209 Tk_Get3DBorderFromObj returns the token for an existing border, given │
211 the window and color name used to create the border. Tk_Get3DBorder‐ │
212 FromObj doesn't actually create the border; it must already have been │
213 created with a previous call to Tk_Alloc3DBorderFromObj or Tk_Get3DBor‐ │
214 der. The return value is cached in objPtr, which speeds up future │
215 calls to Tk_Get3DBorderFromObj with the same objPtr and tkwin.
216 Once a border structure has been created, Tk_Draw3DRectangle may be
218 invoked to draw the border. The tkwin argument specifies the window
219 for which the border was allocated, and drawable specifies a window or
220 pixmap in which the border is to be drawn. Drawable need not refer to
221 the same window as tkwin, but it must refer to a compatible pixmap or
222 window: one associated with the same screen and with the same depth as
223 tkwin. The x, y, width, and height arguments define the bounding box
224 of the border region within drawable (usually x and y are zero and
225 width and height are the dimensions of the window), and borderWidth
226 specifies the number of pixels actually occupied by the border. The
227 relief argument indicates which of several three-dimensional effects is
228 desired: TK_RELIEF_RAISED means that the interior of the rectangle
229 should appear raised relative to the exterior of the rectangle, and
230 TK_RELIEF_SUNKEN means that the interior should appear depressed.
231 TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to
232 be a groove or ridge around the exterior of the rectangle.
233 Tk_Fill3DRectangle is somewhat like Tk_Draw3DRectangle except that it
235 first fills the rectangular area with the background color (one corre‐
236 sponding to the color used to create border). Then it calls
237 Tk_Draw3DRectangle to draw a border just inside the outer edge of the
238 rectangular area. The argument relief indicates the desired effect
239 (TK_RELIEF_FLAT means no border should be drawn; all that happens is to
240 fill the rectangle with the background color).
241 The procedure Tk_Draw3DPolygon may be used to draw more complex shapes
243 with a three-dimensional appearance. The pointPtr and numPoints argu‐
244 ments define a trajectory, polyBorderWidth indicates how wide the bor‐
245 der should be (and on which side of the trajectory to draw it), and
246 leftRelief indicates which side of the trajectory should appear raised.
247 Tk_Draw3DPolygon draws a border around the given trajectory using the
248 colors from border to produce a three-dimensional appearance. If the
249 trajectory is non-self-intersecting, the appearance will be a raised or
250 sunken polygon shape. The trajectory may be self-intersecting,
251 although it's not clear how useful this is.
252 Tk_Fill3DPolygon is to Tk_Draw3DPolygon what Tk_Fill3DRectangle is to
254 Tk_Draw3DRectangle: it fills the polygonal area with the background
255 color from border, then calls Tk_Draw3DPolygon to draw a border around
256 the area (unless leftRelief is TK_RELIEF_FLAT; in this case no border
257 is drawn).
258 The procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel provide
260 lower-level drawing primitives that are used by procedures such as
261 Tk_Draw3DRectangle. These procedures are also useful in their own
262 right for drawing rectilinear border shapes. Tk_3DVerticalBevel draws
263 a vertical beveled edge, such as the left or right side of a rectangle,
264 and Tk_3DHorizontalBevel draws a horizontal beveled edge, such as the
265 top or bottom of a rectangle. Each procedure takes x, y, width, and
266 height arguments that describe the rectangular area of the beveled edge
267 (e.g., width is the border width for Tk_3DVerticalBevel). The leftBor‐
268 der and topBorder arguments indicate the position of the border rela‐
269 tive to the ``inside'' of the object, and relief indicates the relief
270 of the inside of the object relative to the outside. Tk_3DVertical‐
271 Bevel just draws a rectangular region. Tk_3DHorizontalBevel draws a
272 trapezoidal region to generate mitered corners; it should be called
273 after Tk_3DVerticalBevel (otherwise Tk_3DVerticalBevel will overwrite
274 the mitering in the corner). The leftIn and rightIn arguments to
275 Tk_3DHorizontalBevel describe the mitering at the corners; a value of
276 1 means that the bottom edge of the trapezoid will be shorter than the
277 top, 0 means it will be longer. For example, to draw a rectangular
278 border the top bevel should be drawn with 1 for both leftIn and
279 rightIn, and the bottom bevel should be drawn with 0 for both argu‐
280 ments.
281 The procedure Tk_SetBackgroundFromBorder will modify the background
283 pixel and/or pixmap of tkwin to produce a result compatible with bor‐
284 der. For color displays, the resulting background will just be the
285 color specified when border was created; for monochrome displays, the
286 resulting background will be a light stipple pattern, in order to dis‐
287 tinguish the background from the illuminated portion of the border.
288 Given a token for a border, the procedure Tk_NameOf3DBorder will return
290 the color name that was used to create the border.
291 The procedure Tk_3DBorderColor returns the XColor structure that will
293 be used for flat surfaces drawn for its border argument by procedures
294 like Tk_Fill3DRectangle. The return value corresponds to the color
295 name that was used to create the border. The XColor, and its associ‐
296 ated pixel value, will remain allocated as long as border exists.
297 The procedure Tk_3DBorderGC returns one of the X graphics contexts that
299 are used to draw the border. The argument which selects which one of
300 the three possible GC's: TK_3D_FLAT_GC returns the context used for
301 flat surfaces, TK_3D_LIGHT_GC returns the context for light shadows,
302 and TK_3D_DARK_GC returns the context for dark shadows.
303 When a border is no longer needed, Tk_Free3DBorderFromObj or │
305 Tk_Free3DBorder should be called to release the resources associated │
306 with it. For Tk_Free3DBorderFromObj the border to release is specified │
307 with the window and color name used to create the border; for │
308 Tk_Free3DBorder the border to release is specified with the Tk_3DBorder │
309 token for the border. There should be exactly one call to │
310 Tk_Free3DBorderFromObj or Tk_Free3DBorder for each call to │
311 Tk_Alloc3DBorderFromObj or Tk_Get3DBorder.
312
315 3D, background, border, color, depressed, illumination, object, poly‐
316 gon, raised, shadow, three-dimensional effect
317Tk 8.1 Tk_Alloc3DBorderFromObj(3)