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 value 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 a value.
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 value 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 value; zero
153 means it forms the right side.
154 int leftIn (in) Non-zero means that the left edge
156 of the horizontal bevel angles
157 in, so that the bottom of the
158 edge is farther to the right than
159 the top. Zero means the edge
160 angles out, so that the bottom is
161 farther to the left than the top.
162 int rightIn (in) Non-zero means that the right
164 edge of the horizontal bevel
165 angles in, so that the bottom of
166 the edge is farther to the left
167 than the top. Zero means the
168 edge angles out, so that the bot‐
169 tom is farther to the right than
170 the top.
171 int topBevel (in) Non-zero means this bevel forms
173 the top side of the value; zero
174 means it forms the bottom side.
175 int which (in) Specifies which of the border's
177 graphics contexts is desired.
178 Must be TK_3D_FLAT_GC,
179 TK_3D_LIGHT_GC, or TK_3D_DARK_GC.
180______________________________________________________________________________
181
183 These procedures provide facilities for drawing window borders in a way
184 that produces a three-dimensional appearance. Tk_Alloc3DBorderFromObj
185 allocates colors and Pixmaps needed to draw a border in the window
186 given by the tkwin argument. The value of objPtr is a standard Tk
187 color name that determines the border colors. The color indicated by
188 objPtr will not actually be used in the border; it indicates the back‐
189 ground color for the window (i.e. a color for flat surfaces). The
190 illuminated portions of the border will appear brighter than indicated
191 by objPtr, and the shadowed portions of the border will appear darker
192 than objPtr.
193 Tk_Alloc3DBorderFromObj returns a token that may be used in later calls
195 to Tk_Draw3DRectangle. If an error occurs in allocating information
196 for the border (e.g. a bogus color name was given) then NULL is
197 returned and an error message is left as the result of interpreter
198 interp. If it returns successfully, Tk_Alloc3DBorderFromObj caches
199 information about the return value in objPtr, which speeds up future
200 calls to Tk_Alloc3DBorderFromObj with the same objPtr and tkwin.
201 Tk_Get3DBorder is identical to Tk_Alloc3DBorderFromObj except that the
203 color is specified with a string instead of a value. This prevents
204 Tk_Get3DBorder from caching the return value, so Tk_Get3DBorder is less
205 efficient than Tk_Alloc3DBorderFromObj.
206 Tk_Get3DBorderFromObj returns the token for an existing border, given
208 the window and color name used to create the border. Tk_Get3DBorder‐
209 FromObj does not actually create the border; it must already have been
210 created with a previous call to Tk_Alloc3DBorderFromObj or Tk_Get3DBor‐
211 der. The return value is cached in objPtr, which speeds up future
212 calls to Tk_Get3DBorderFromObj with the same objPtr and tkwin.
213 Once a border structure has been created, Tk_Draw3DRectangle may be
215 invoked to draw the border. The tkwin argument specifies the window
216 for which the border was allocated, and drawable specifies a window or
217 pixmap in which the border is to be drawn. Drawable need not refer to
218 the same window as tkwin, but it must refer to a compatible pixmap or
219 window: one associated with the same screen and with the same depth as
220 tkwin. The x, y, width, and height arguments define the bounding box
221 of the border region within drawable (usually x and y are zero and
222 width and height are the dimensions of the window), and borderWidth
223 specifies the number of pixels actually occupied by the border. The
224 relief argument indicates which of several three-dimensional effects is
225 desired: TK_RELIEF_RAISED means that the interior of the rectangle
226 should appear raised relative to the exterior of the rectangle, and
227 TK_RELIEF_SUNKEN means that the interior should appear depressed.
228 TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to
229 be a groove or ridge around the exterior of the rectangle.
230 Tk_Fill3DRectangle is somewhat like Tk_Draw3DRectangle except that it
232 first fills the rectangular area with the background color (one corre‐
233 sponding to the color used to create border). Then it calls
234 Tk_Draw3DRectangle to draw a border just inside the outer edge of the
235 rectangular area. The argument relief indicates the desired effect
236 (TK_RELIEF_FLAT means no border should be drawn; all that happens is to
237 fill the rectangle with the background color).
238 The procedure Tk_Draw3DPolygon may be used to draw more complex shapes
240 with a three-dimensional appearance. The pointPtr and numPoints argu‐
241 ments define a trajectory, polyBorderWidth indicates how wide the bor‐
242 der should be (and on which side of the trajectory to draw it), and
243 leftRelief indicates which side of the trajectory should appear raised.
244 Tk_Draw3DPolygon draws a border around the given trajectory using the
245 colors from border to produce a three-dimensional appearance. If the
246 trajectory is non-self-intersecting, the appearance will be a raised or
247 sunken polygon shape. The trajectory may be self-intersecting,
248 although it's not clear how useful this is.
249 Tk_Fill3DPolygon is to Tk_Draw3DPolygon what Tk_Fill3DRectangle is to
251 Tk_Draw3DRectangle: it fills the polygonal area with the background
252 color from border, then calls Tk_Draw3DPolygon to draw a border around
253 the area (unless leftRelief is TK_RELIEF_FLAT; in this case no border
254 is drawn).
255 The procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel provide
257 lower-level drawing primitives that are used by procedures such as
258 Tk_Draw3DRectangle. These procedures are also useful in their own
259 right for drawing rectilinear border shapes. Tk_3DVerticalBevel draws
260 a vertical beveled edge, such as the left or right side of a rectangle,
261 and Tk_3DHorizontalBevel draws a horizontal beveled edge, such as the
262 top or bottom of a rectangle. Each procedure takes x, y, width, and
263 height arguments that describe the rectangular area of the beveled edge
264 (e.g., width is the border width for Tk_3DVerticalBevel). The leftBor‐
265 der and topBorder arguments indicate the position of the border rela‐
266 tive to the “inside” of the value, and relief indicates the relief of
267 the inside of the value relative to the outside. Tk_3DVerticalBevel
268 just draws a rectangular region. Tk_3DHorizontalBevel draws a trape‐
269 zoidal region to generate mitered corners; it should be called after
270 Tk_3DVerticalBevel (otherwise Tk_3DVerticalBevel will overwrite the
271 mitering in the corner). The leftIn and rightIn arguments to Tk_3DHor‐
272 izontalBevel describe the mitering at the corners; a value of 1 means
273 that the bottom edge of the trapezoid will be shorter than the top, 0
274 means it will be longer. For example, to draw a rectangular border the
275 top bevel should be drawn with 1 for both leftIn and rightIn, and the
276 bottom bevel should be drawn with 0 for both arguments.
277 The procedure Tk_SetBackgroundFromBorder will modify the background
279 pixel and/or pixmap of tkwin to produce a result compatible with bor‐
280 der. For color displays, the resulting background will just be the
281 color specified when border was created; for monochrome displays, the
282 resulting background will be a light stipple pattern, in order to dis‐
283 tinguish the background from the illuminated portion of the border.
284 Given a token for a border, the procedure Tk_NameOf3DBorder will return
286 the color name that was used to create the border.
287 The procedure Tk_3DBorderColor returns the XColor structure that will
289 be used for flat surfaces drawn for its border argument by procedures
290 like Tk_Fill3DRectangle. The return value corresponds to the color
291 name that was used to create the border. The XColor, and its associ‐
292 ated pixel value, will remain allocated as long as border exists.
293 The procedure Tk_3DBorderGC returns one of the X graphics contexts that
295 are used to draw the border. The argument which selects which one of
296 the three possible GC's: TK_3D_FLAT_GC returns the context used for
297 flat surfaces, TK_3D_LIGHT_GC returns the context for light shadows,
298 and TK_3D_DARK_GC returns the context for dark shadows.
299 When a border is no longer needed, Tk_Free3DBorderFromObj or
301 Tk_Free3DBorder should be called to release the resources associated
302 with it. For Tk_Free3DBorderFromObj the border to release is specified
303 with the window and color name used to create the border; for
304 Tk_Free3DBorder the border to release is specified with the Tk_3DBorder
305 token for the border. There should be exactly one call to
306 Tk_Free3DBorderFromObj or Tk_Free3DBorder for each call to
307 Tk_Alloc3DBorderFromObj or Tk_Get3DBorder.
308
310 3D, background, border, color, depressed, illumination, value, polygon,
311 raised, shadow, three-dimensional effect
312Tk 8.1 Tk_Alloc3DBorderFromObj(3)