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-di‐
13 mensional 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 re‐
63 porting.
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 de‐
71 scribes 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 tk‐
86 win.
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, TK_RE‐
115 LIEF_GROOVE, TK_RELIEF_SOLID, or
116 TK_RELIEF_RIDGE (may also be
117 TK_RELIEF_FLAT for Tk_Fill3DRect‐
118 angle).
119 XPoint *pointPtr (in) Pointer to array of points de‐
121 scribing the set of vertices in a
122 polygon. The polygon need not be
123 closed (it will be closed auto‐
124 matically if it is not).
125 int numPoints (in) Number of points at *pointPtr.
127 int polyBorderWidth (in) Width of border in pixels. If
129 positive, border is drawn to left
130 of trajectory given by pointPtr;
131 if negative, border is drawn to
132 right of trajectory. If leftRe‐
133 lief is TK_RELIEF_GROOVE or
134 TK_RELIEF_RIDGE then the border
135 is centered on the trajectory.
136 int leftRelief (in) Height of left side of polygon's
138 path relative to right. TK_RE‐
139 LIEF_RAISED means left side
140 should appear higher and TK_RE‐
141 LIEF_SUNKEN means right side
142 should appear higher; TK_RE‐
143 LIEF_GROOVE and TK_RELIEF_RIDGE
144 mean the obvious things. For
145 Tk_Fill3DPolygon, TK_RELIEF_FLAT
146 may also be specified to indicate
147 no difference in height.
148 int leftBevel (in) Non-zero means this bevel forms
150 the left side of the value; zero
151 means it forms the right side.
152 int leftIn (in) Non-zero means that the left edge
154 of the horizontal bevel angles
155 in, so that the bottom of the
156 edge is farther to the right than
157 the top. Zero means the edge an‐
158 gles out, so that the bottom is
159 farther to the left than the top.
160 int rightIn (in) Non-zero means that the right
162 edge of the horizontal bevel an‐
163 gles in, so that the bottom of
164 the edge is farther to the left
165 than the top. Zero means the
166 edge angles out, so that the bot‐
167 tom is farther to the right than
168 the top.
169 int topBevel (in) Non-zero means this bevel forms
171 the top side of the value; zero
172 means it forms the bottom side.
173 int which (in) Specifies which of the border's
175 graphics contexts is desired.
176 Must be TK_3D_FLAT_GC,
177 TK_3D_LIGHT_GC, or TK_3D_DARK_GC.
178______________________________________________________________________________
179
181 These procedures provide facilities for drawing window borders in a way
182 that produces a three-dimensional appearance. Tk_Alloc3DBorderFromObj
183 allocates colors and Pixmaps needed to draw a border in the window
184 given by the tkwin argument. The value of objPtr is a standard Tk
185 color name that determines the border colors. The color indicated by
186 objPtr will not actually be used in the border; it indicates the back‐
187 ground color for the window (i.e. a color for flat surfaces). The il‐
188 luminated portions of the border will appear brighter than indicated by
189 objPtr, and the shadowed portions of the border will appear darker than
190 objPtr.
191 Tk_Alloc3DBorderFromObj returns a token that may be used in later calls
193 to Tk_Draw3DRectangle. If an error occurs in allocating information
194 for the border (e.g. a bogus color name was given) then NULL is re‐
195 turned and an error message is left as the result of interpreter in‐
196 terp. If it returns successfully, Tk_Alloc3DBorderFromObj caches in‐
197 formation about the return value in objPtr, which speeds up future
198 calls to Tk_Alloc3DBorderFromObj with the same objPtr and tkwin.
199 Tk_Get3DBorder is identical to Tk_Alloc3DBorderFromObj except that the
201 color is specified with a string instead of a value. This prevents
202 Tk_Get3DBorder from caching the return value, so Tk_Get3DBorder is less
203 efficient than Tk_Alloc3DBorderFromObj.
204 Tk_Get3DBorderFromObj returns the token for an existing border, given
206 the window and color name used to create the border. Tk_Get3DBorder‐
207 FromObj does not actually create the border; it must already have been
208 created with a previous call to Tk_Alloc3DBorderFromObj or Tk_Get3DBor‐
209 der. The return value is cached in objPtr, which speeds up future
210 calls to Tk_Get3DBorderFromObj with the same objPtr and tkwin.
211 Once a border structure has been created, Tk_Draw3DRectangle may be in‐
213 voked to draw the border. The tkwin argument specifies the window for
214 which the border was allocated, and drawable specifies a window or
215 pixmap in which the border is to be drawn. Drawable need not refer to
216 the same window as tkwin, but it must refer to a compatible pixmap or
217 window: one associated with the same screen and with the same depth as
218 tkwin. The x, y, width, and height arguments define the bounding box
219 of the border region within drawable (usually x and y are zero and
220 width and height are the dimensions of the window), and borderWidth
221 specifies the number of pixels actually occupied by the border. The
222 relief argument indicates which of several three-dimensional effects is
223 desired: TK_RELIEF_RAISED means that the interior of the rectangle
224 should appear raised relative to the exterior of the rectangle, and
225 TK_RELIEF_SUNKEN means that the interior should appear depressed.
226 TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to
227 be a groove or ridge around the exterior of the rectangle.
228 Tk_Fill3DRectangle is somewhat like Tk_Draw3DRectangle except that it
230 first fills the rectangular area with the background color (one corre‐
231 sponding to the color used to create border). Then it calls
232 Tk_Draw3DRectangle to draw a border just inside the outer edge of the
233 rectangular area. The argument relief indicates the desired effect
234 (TK_RELIEF_FLAT means no border should be drawn; all that happens is to
235 fill the rectangle with the background color).
236 The procedure Tk_Draw3DPolygon may be used to draw more complex shapes
238 with a three-dimensional appearance. The pointPtr and numPoints argu‐
239 ments define a trajectory, polyBorderWidth indicates how wide the bor‐
240 der should be (and on which side of the trajectory to draw it), and
241 leftRelief indicates which side of the trajectory should appear raised.
242 Tk_Draw3DPolygon draws a border around the given trajectory using the
243 colors from border to produce a three-dimensional appearance. If the
244 trajectory is non-self-intersecting, the appearance will be a raised or
245 sunken polygon shape. The trajectory may be self-intersecting, al‐
246 though it's not clear how useful this is.
247 Tk_Fill3DPolygon is to Tk_Draw3DPolygon what Tk_Fill3DRectangle is to
249 Tk_Draw3DRectangle: it fills the polygonal area with the background
250 color from border, then calls Tk_Draw3DPolygon to draw a border around
251 the area (unless leftRelief is TK_RELIEF_FLAT; in this case no border
252 is drawn).
253 The procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel provide
255 lower-level drawing primitives that are used by procedures such as
256 Tk_Draw3DRectangle. These procedures are also useful in their own
257 right for drawing rectilinear border shapes. Tk_3DVerticalBevel draws
258 a vertical beveled edge, such as the left or right side of a rectangle,
259 and Tk_3DHorizontalBevel draws a horizontal beveled edge, such as the
260 top or bottom of a rectangle. Each procedure takes x, y, width, and
261 height arguments that describe the rectangular area of the beveled edge
262 (e.g., width is the border width for Tk_3DVerticalBevel). The leftBor‐
263 der and topBorder arguments indicate the position of the border rela‐
264 tive to the “inside” of the value, and relief indicates the relief of
265 the inside of the value relative to the outside. Tk_3DVerticalBevel
266 just draws a rectangular region. Tk_3DHorizontalBevel draws a trape‐
267 zoidal region to generate mitered corners; it should be called after
268 Tk_3DVerticalBevel (otherwise Tk_3DVerticalBevel will overwrite the mi‐
269 tering in the corner). The leftIn and rightIn arguments to Tk_3DHori‐
270 zontalBevel describe the mitering at the corners; a value of 1 means
271 that the bottom edge of the trapezoid will be shorter than the top, 0
272 means it will be longer. For example, to draw a rectangular border the
273 top bevel should be drawn with 1 for both leftIn and rightIn, and the
274 bottom bevel should be drawn with 0 for both arguments.
275 The procedure Tk_SetBackgroundFromBorder will modify the background
277 pixel and/or pixmap of tkwin to produce a result compatible with bor‐
278 der. For color displays, the resulting background will just be the
279 color specified when border was created; for monochrome displays, the
280 resulting background will be a light stipple pattern, in order to dis‐
281 tinguish the background from the illuminated portion of the border.
282 Given a token for a border, the procedure Tk_NameOf3DBorder will return
284 the color name that was used to create the border.
285 The procedure Tk_3DBorderColor returns the XColor structure that will
287 be used for flat surfaces drawn for its border argument by procedures
288 like Tk_Fill3DRectangle. The return value corresponds to the color
289 name that was used to create the border. The XColor, and its associ‐
290 ated pixel value, will remain allocated as long as border exists.
291 The procedure Tk_3DBorderGC returns one of the X graphics contexts that
293 are used to draw the border. The argument which selects which one of
294 the three possible GC's: TK_3D_FLAT_GC returns the context used for
295 flat surfaces, TK_3D_LIGHT_GC returns the context for light shadows,
296 and TK_3D_DARK_GC returns the context for dark shadows.
297 When a border is no longer needed, Tk_Free3DBorderFromObj or
299 Tk_Free3DBorder should be called to release the resources associated
300 with it. For Tk_Free3DBorderFromObj the border to release is specified
301 with the window and color name used to create the border; for
302 Tk_Free3DBorder the border to release is specified with the Tk_3DBorder
303 token for the border. There should be exactly one call to
304 Tk_Free3DBorderFromObj or Tk_Free3DBorder for each call to Tk_Al‐
305 loc3DBorderFromObj or Tk_Get3DBorder.
306
308 3D, background, border, color, depressed, illumination, value, polygon,
309 raised, shadow, three-dimensional effect
310Tk 8.1 Tk_Alloc3DBorderFromObj(3)