Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1990-1993 The Regents of the University of California. | |
3 | '\" Copyright (c) 1994-1998 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: 3DBorder.3,v 1.4 2002/08/05 04:30:38 dgp Exp $ | |
9 | '\" | |
10 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
11 | '\" manual entries. | |
12 | '\" | |
13 | '\" .AP type name in/out ?indent? | |
14 | '\" Start paragraph describing an argument to a library procedure. | |
15 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
16 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
17 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
18 | '\" needed; use .AS below instead) | |
19 | '\" | |
20 | '\" .AS ?type? ?name? | |
21 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
22 | '\" name are examples of largest possible arguments that will be passed | |
23 | '\" to .AP later. If args are omitted, default tab stops are used. | |
24 | '\" | |
25 | '\" .BS | |
26 | '\" Start box enclosure. From here until next .BE, everything will be | |
27 | '\" enclosed in one large box. | |
28 | '\" | |
29 | '\" .BE | |
30 | '\" End of box enclosure. | |
31 | '\" | |
32 | '\" .CS | |
33 | '\" Begin code excerpt. | |
34 | '\" | |
35 | '\" .CE | |
36 | '\" End code excerpt. | |
37 | '\" | |
38 | '\" .VS ?version? ?br? | |
39 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
40 | '\" of man pages. The first argument is ignored and used for recording | |
41 | '\" the version when the .VS was added, so that the sidebars can be | |
42 | '\" found and removed when they reach a certain age. If another argument | |
43 | '\" is present, then a line break is forced before starting the sidebar. | |
44 | '\" | |
45 | '\" .VE | |
46 | '\" End of vertical sidebar. | |
47 | '\" | |
48 | '\" .DS | |
49 | '\" Begin an indented unfilled display. | |
50 | '\" | |
51 | '\" .DE | |
52 | '\" End of indented unfilled display. | |
53 | '\" | |
54 | '\" .SO | |
55 | '\" Start of list of standard options for a Tk widget. The | |
56 | '\" options follow on successive lines, in four columns separated | |
57 | '\" by tabs. | |
58 | '\" | |
59 | '\" .SE | |
60 | '\" End of list of standard options for a Tk widget. | |
61 | '\" | |
62 | '\" .OP cmdName dbName dbClass | |
63 | '\" Start of description of a specific option. cmdName gives the | |
64 | '\" option's name as specified in the class command, dbName gives | |
65 | '\" the option's name in the option database, and dbClass gives | |
66 | '\" the option's class in the option database. | |
67 | '\" | |
68 | '\" .UL arg1 arg2 | |
69 | '\" Print arg1 underlined, then print arg2 normally. | |
70 | '\" | |
71 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
72 | '\" | |
73 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
74 | .if t .wh -1.3i ^B | |
75 | .nr ^l \n(.l | |
76 | .ad b | |
77 | '\" # Start an argument description | |
78 | .de AP | |
79 | .ie !"\\$4"" .TP \\$4 | |
80 | .el \{\ | |
81 | . ie !"\\$2"" .TP \\n()Cu | |
82 | . el .TP 15 | |
83 | .\} | |
84 | .ta \\n()Au \\n()Bu | |
85 | .ie !"\\$3"" \{\ | |
86 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
87 | .\".b | |
88 | .\} | |
89 | .el \{\ | |
90 | .br | |
91 | .ie !"\\$2"" \{\ | |
92 | \&\\$1 \\fI\\$2\\fP | |
93 | .\} | |
94 | .el \{\ | |
95 | \&\\fI\\$1\\fP | |
96 | .\} | |
97 | .\} | |
98 | .. | |
99 | '\" # define tabbing values for .AP | |
100 | .de AS | |
101 | .nr )A 10n | |
102 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
103 | .nr )B \\n()Au+15n | |
104 | .\" | |
105 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
106 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
107 | .. | |
108 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
109 | '\" # BS - start boxed text | |
110 | '\" # ^y = starting y location | |
111 | '\" # ^b = 1 | |
112 | .de BS | |
113 | .br | |
114 | .mk ^y | |
115 | .nr ^b 1u | |
116 | .if n .nf | |
117 | .if n .ti 0 | |
118 | .if n \l'\\n(.lu\(ul' | |
119 | .if n .fi | |
120 | .. | |
121 | '\" # BE - end boxed text (draw box now) | |
122 | .de BE | |
123 | .nf | |
124 | .ti 0 | |
125 | .mk ^t | |
126 | .ie n \l'\\n(^lu\(ul' | |
127 | .el \{\ | |
128 | .\" Draw four-sided box normally, but don't draw top of | |
129 | .\" box if the box started on an earlier page. | |
130 | .ie !\\n(^b-1 \{\ | |
131 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
132 | .\} | |
133 | .el \}\ | |
134 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
135 | .\} | |
136 | .\} | |
137 | .fi | |
138 | .br | |
139 | .nr ^b 0 | |
140 | .. | |
141 | '\" # VS - start vertical sidebar | |
142 | '\" # ^Y = starting y location | |
143 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
144 | .de VS | |
145 | .if !"\\$2"" .br | |
146 | .mk ^Y | |
147 | .ie n 'mc \s12\(br\s0 | |
148 | .el .nr ^v 1u | |
149 | .. | |
150 | '\" # VE - end of vertical sidebar | |
151 | .de VE | |
152 | .ie n 'mc | |
153 | .el \{\ | |
154 | .ev 2 | |
155 | .nf | |
156 | .ti 0 | |
157 | .mk ^t | |
158 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
159 | .sp -1 | |
160 | .fi | |
161 | .ev | |
162 | .\} | |
163 | .nr ^v 0 | |
164 | .. | |
165 | '\" # Special macro to handle page bottom: finish off current | |
166 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
167 | '\" # page bottom macro. | |
168 | .de ^B | |
169 | .ev 2 | |
170 | 'ti 0 | |
171 | 'nf | |
172 | .mk ^t | |
173 | .if \\n(^b \{\ | |
174 | .\" Draw three-sided box if this is the box's first page, | |
175 | .\" draw two sides but no top otherwise. | |
176 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
177 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
178 | .\} | |
179 | .if \\n(^v \{\ | |
180 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
181 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
182 | .\} | |
183 | .bp | |
184 | 'fi | |
185 | .ev | |
186 | .if \\n(^b \{\ | |
187 | .mk ^y | |
188 | .nr ^b 2 | |
189 | .\} | |
190 | .if \\n(^v \{\ | |
191 | .mk ^Y | |
192 | .\} | |
193 | .. | |
194 | '\" # DS - begin display | |
195 | .de DS | |
196 | .RS | |
197 | .nf | |
198 | .sp | |
199 | .. | |
200 | '\" # DE - end display | |
201 | .de DE | |
202 | .fi | |
203 | .RE | |
204 | .sp | |
205 | .. | |
206 | '\" # SO - start of list of standard options | |
207 | .de SO | |
208 | .SH "STANDARD OPTIONS" | |
209 | .LP | |
210 | .nf | |
211 | .ta 5.5c 11c | |
212 | .ft B | |
213 | .. | |
214 | '\" # SE - end of list of standard options | |
215 | .de SE | |
216 | .fi | |
217 | .ft R | |
218 | .LP | |
219 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
220 | .. | |
221 | '\" # OP - start of full description for a single option | |
222 | .de OP | |
223 | .LP | |
224 | .nf | |
225 | .ta 4c | |
226 | Command-Line Name: \\fB\\$1\\fR | |
227 | Database Name: \\fB\\$2\\fR | |
228 | Database Class: \\fB\\$3\\fR | |
229 | .fi | |
230 | .IP | |
231 | .. | |
232 | '\" # CS - begin code excerpt | |
233 | .de CS | |
234 | .RS | |
235 | .nf | |
236 | .ta .25i .5i .75i 1i | |
237 | .. | |
238 | '\" # CE - end code excerpt | |
239 | .de CE | |
240 | .fi | |
241 | .RE | |
242 | .. | |
243 | .de UL | |
244 | \\$1\l'|0\(ul'\\$2 | |
245 | .. | |
246 | .TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures" | |
247 | .BS | |
248 | .SH NAME | |
249 | Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance | |
250 | .SH SYNOPSIS | |
251 | .nf | |
252 | \fB#include <tk.h>\fR | |
253 | .sp | |
254 | .VS 8.1 | |
255 | Tk_3DBorder | |
256 | \fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR | |
257 | .sp | |
258 | Tk_3DBorder | |
259 | \fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR | |
260 | .sp | |
261 | Tk_3DBorder | |
262 | \fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR | |
263 | .VE | |
264 | .sp | |
265 | void | |
266 | \fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR | |
267 | .sp | |
268 | void | |
269 | \fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR | |
270 | .sp | |
271 | void | |
272 | \fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR | |
273 | .sp | |
274 | void | |
275 | \fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR | |
276 | .sp | |
277 | void | |
278 | \fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR | |
279 | .sp | |
280 | void | |
281 | \fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR | |
282 | .sp | |
283 | void | |
284 | \fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR | |
285 | .sp | |
286 | CONST char * | |
287 | \fBTk_NameOf3DBorder(\fIborder\fB)\fR | |
288 | .sp | |
289 | XColor * | |
290 | \fBTk_3DBorderColor(\fIborder\fB)\fR | |
291 | .sp | |
292 | GC * | |
293 | \fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR | |
294 | .sp | |
295 | .VS 8.1 | |
296 | \fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR | |
297 | .VE | |
298 | .sp | |
299 | \fBTk_Free3DBorder(\fIborder\fB)\fR | |
300 | .SH ARGUMENTS | |
301 | .AS "Tk_3DBorder" borderWidth | |
302 | .AP Tcl_Interp *interp in | |
303 | Interpreter to use for error reporting. | |
304 | .AP Tk_Window tkwin in | |
305 | Token for window (for all procedures except \fBTk_Get3DBorder\fR, | |
306 | must be the window for which the border was allocated). | |
307 | .AP Tcl_Obj *objPtr in | |
308 | .VS 8.1 | |
309 | Pointer to object whose value describes color corresponding to | |
310 | background (flat areas). Illuminated edges will be brighter than | |
311 | this and shadowed edges will be darker than this. | |
312 | .AP char *colorName in | |
313 | Same as \fIobjPtr\fR except value is supplied as a string rather | |
314 | than an object. | |
315 | .VE | |
316 | .AP Drawable drawable in | |
317 | X token for window or pixmap; indicates where graphics are to be drawn. | |
318 | Must either be the X window for \fItkwin\fR or a pixmap with the | |
319 | same screen and depth as \fItkwin\fR. | |
320 | .AP Tk_3DBorder border in | |
321 | Token for border previously allocated in call to \fBTk_Get3DBorder\fR. | |
322 | .AP int x in | |
323 | X-coordinate of upper-left corner of rectangle describing border | |
324 | or bevel, in pixels. | |
325 | .AP int y in | |
326 | Y-coordinate of upper-left corner of rectangle describing border or | |
327 | bevel, in pixels. | |
328 | .AP int width in | |
329 | Width of rectangle describing border or bevel, in pixels. | |
330 | .AP int height in | |
331 | Height of rectangle describing border or bevel, in pixels. | |
332 | .AP int borderWidth in | |
333 | Width of border in pixels. Positive means border is inside rectangle | |
334 | given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means | |
335 | border is outside rectangle. | |
336 | .AP int relief in | |
337 | Indicates 3-D position of interior of object relative to exterior; | |
338 | should be TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, | |
339 | TK_RELIEF_SOLID, or TK_RELIEF_RIDGE (may also be TK_RELIEF_FLAT | |
340 | for \fBTk_Fill3DRectangle\fR). | |
341 | .AP XPoint *pointPtr in | |
342 | Pointer to array of points describing the set of vertices in a polygon. | |
343 | The polygon need not be closed (it will be closed automatically if it | |
344 | isn't). | |
345 | .AP int numPoints in | |
346 | Number of points at \fI*pointPtr\fR. | |
347 | .AP int polyBorderWidth in | |
348 | Width of border in pixels. If positive, border is drawn to left of | |
349 | trajectory given by \fIpointPtr\fR; if negative, border is drawn to | |
350 | right of trajectory. If \fIleftRelief\fR is TK_RELIEF_GROOVE or | |
351 | TK_RELIEF_RIDGE then the border is centered on the trajectory. | |
352 | .AP int leftRelief in | |
353 | Height of left side of polygon's path relative to right. TK_RELIEF_RAISED | |
354 | means left side should appear higher and TK_RELIEF_SUNKEN means right side | |
355 | should appear higher; | |
356 | TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things. | |
357 | For \fBTk_Fill3DPolygon\fR, TK_RELIEF_FLAT may also be specified to | |
358 | indicate no difference in height. | |
359 | .AP int leftBevel in | |
360 | Non-zero means this bevel forms the left side of the object; zero means | |
361 | it forms the right side. | |
362 | .AP int leftIn in | |
363 | Non-zero means that the left edge of the horizontal bevel angles in, | |
364 | so that the bottom of the edge is farther to the right than | |
365 | the top. | |
366 | Zero means the edge angles out, so that the bottom is farther to the | |
367 | left than the top. | |
368 | .AP int rightIn in | |
369 | Non-zero means that the right edge of the horizontal bevel angles in, | |
370 | so that the bottom of the edge is farther to the left than the top. | |
371 | Zero means the edge angles out, so that the bottom is farther to the | |
372 | right than the top. | |
373 | .AP int topBevel in | |
374 | Non-zero means this bevel forms the top side of the object; zero means | |
375 | it forms the bottom side. | |
376 | .AP int which in | |
377 | Specifies which of the border's graphics contexts is desired. | |
378 | Must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC. | |
379 | .BE | |
380 | ||
381 | .SH DESCRIPTION | |
382 | .PP | |
383 | These procedures provide facilities for drawing window borders in a | |
384 | way that produces a three-dimensional appearance. | |
385 | .VS 8.1 | |
386 | \fBTk_Alloc3DBorderFromObj\fR | |
387 | allocates colors and Pixmaps needed to draw a border in the window | |
388 | given by the \fItkwin\fR argument. The value of \fIobjPtr\fR | |
389 | is a standard Tk color name that determines the border colors. | |
390 | The color indicated by \fIobjPtr\fR will not actually be used in | |
391 | the border; it indicates the background color for the window | |
392 | (i.e. a color for flat surfaces). | |
393 | The illuminated portions of the border will appear brighter than indicated | |
394 | by \fIobjPtr\fR, and the shadowed portions of the border will appear | |
395 | darker than \fIobjPtr\fR. | |
396 | .PP | |
397 | \fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls | |
398 | to \fBTk_Draw3DRectangle\fR. If an error occurs in allocating information | |
399 | for the border (e.g. a bogus color name was given) | |
400 | then NULL is returned and an error message is left in \fIinterp->result\fR. | |
401 | If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches | |
402 | information about the return value in \fIobjPtr\fR, which speeds up | |
403 | future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR | |
404 | and \fItkwin\fR. | |
405 | .PP | |
406 | \fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except | |
407 | that the color is specified with a string instead of an object. This | |
408 | prevents \fBTk_Get3DBorder\fR from caching the return value, so | |
409 | \fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR. | |
410 | .PP | |
411 | \fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given | |
412 | the window and color name used to create the border. | |
413 | \fBTk_Get3DBorderFromObj\fR doesn't actually create the border; it must | |
414 | already have been created with a previous call to | |
415 | \fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. The return | |
416 | value is cached in \fIobjPtr\fR, which speeds up | |
417 | future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR | |
418 | and \fItkwin\fR. | |
419 | .VE | |
420 | .PP | |
421 | Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be | |
422 | invoked to draw the border. | |
423 | The \fItkwin\fR argument specifies the | |
424 | window for which the border was allocated, and \fIdrawable\fR | |
425 | specifies a window or pixmap in which the border is to be drawn. | |
426 | \fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it | |
427 | must refer to a compatible | |
428 | pixmap or window: one associated with the same screen and with the | |
429 | same depth as \fItkwin\fR. | |
430 | The \fIx\fR, \fIy\fR, \fIwidth\fR, and | |
431 | \fIheight\fR arguments define the bounding box of the border region | |
432 | within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and | |
433 | \fIwidth\fR and \fIheight\fR are the dimensions of the window), and | |
434 | \fIborderWidth\fR specifies the number of pixels actually | |
435 | occupied by the border. The \fIrelief\fR argument indicates | |
436 | which of several three-dimensional effects is desired: | |
437 | TK_RELIEF_RAISED means that the interior of the rectangle should appear raised | |
438 | relative to the exterior of the rectangle, and | |
439 | TK_RELIEF_SUNKEN means that the interior should appear depressed. | |
440 | TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to be | |
441 | a groove or ridge around the exterior of the rectangle. | |
442 | .PP | |
443 | \fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except | |
444 | that it first fills the rectangular area with the background color | |
445 | (one corresponding | |
446 | to the color used to create \fIborder\fR). Then it calls | |
447 | \fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of | |
448 | the rectangular area. The argument \fIrelief\fR indicates the desired | |
449 | effect (TK_RELIEF_FLAT means no border should be drawn; all that | |
450 | happens is to fill the rectangle with the background color). | |
451 | .PP | |
452 | The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex | |
453 | shapes with a three-dimensional appearance. The \fIpointPtr\fR and | |
454 | \fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR | |
455 | indicates how wide the border should be (and on which side of the | |
456 | trajectory to draw it), and \fIleftRelief\fR indicates which side | |
457 | of the trajectory should appear raised. \fBTk_Draw3DPolygon\fR | |
458 | draws a border around the given trajectory using the colors from | |
459 | \fIborder\fR to produce a three-dimensional appearance. If the trajectory is | |
460 | non-self-intersecting, the appearance will be a raised or sunken | |
461 | polygon shape. The trajectory may be self-intersecting, although | |
462 | it's not clear how useful this is. | |
463 | .PP | |
464 | \fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what | |
465 | \fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR: it fills | |
466 | the polygonal area with the background color from \fIborder\fR, | |
467 | then calls \fBTk_Draw3DPolygon\fR to draw a border around the | |
468 | area (unless \fIleftRelief\fR is TK_RELIEF_FLAT; in this case no | |
469 | border is drawn). | |
470 | .PP | |
471 | The procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fR | |
472 | provide lower-level drawing primitives that are used by | |
473 | procedures such as \fBTk_Draw3DRectangle\fR. | |
474 | These procedures are also useful in their own right for drawing | |
475 | rectilinear border shapes. | |
476 | \fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as the | |
477 | left or right side of a rectangle, and \fBTk_3DHorizontalBevel\fR | |
478 | draws a horizontal beveled edge, such as the top or bottom of a | |
479 | rectangle. | |
480 | Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR | |
481 | arguments that describe the rectangular area of the beveled edge | |
482 | (e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR). | |
483 | The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the | |
484 | position of the border relative to the ``inside'' of the object, and | |
485 | \fIrelief\fR indicates the relief of the inside of the object relative | |
486 | to the outside. | |
487 | \fBTk_3DVerticalBevel\fR just draws a rectangular region. | |
488 | \fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate | |
489 | mitered corners; it should be called after \fBTk_3DVerticalBevel\fR | |
490 | (otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering in | |
491 | the corner). | |
492 | The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fR | |
493 | describe the mitering at the corners; a value of 1 means that the bottom | |
494 | edge of the trapezoid will be shorter than the top, 0 means it will | |
495 | be longer. | |
496 | For example, to draw a rectangular border the top bevel should be | |
497 | drawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and the | |
498 | bottom bevel should be drawn with 0 for both arguments. | |
499 | .PP | |
500 | The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background | |
501 | pixel and/or pixmap of \fItkwin\fR to produce a result compatible | |
502 | with \fIborder\fR. For color displays, the resulting background will | |
503 | just be the color specified when \fIborder\fR was created; for monochrome | |
504 | displays, the resulting background | |
505 | will be a light stipple pattern, in order to distinguish the background from | |
506 | the illuminated portion of the border. | |
507 | .PP | |
508 | Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR | |
509 | will return the color name that was used to create the border. | |
510 | .PP | |
511 | The procedure \fBTk_3DBorderColor\fR returns the XColor structure | |
512 | that will be used for flat surfaces drawn for its \fIborder\fR | |
513 | argument by procedures like \fBTk_Fill3DRectangle\fR. | |
514 | The return value corresponds to the color name that was used to | |
515 | create the border. | |
516 | The XColor, and its associated pixel value, will remain allocated | |
517 | as long as \fIborder\fR exists. | |
518 | .PP | |
519 | The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts | |
520 | that are used to draw the border. | |
521 | The argument \fIwhich\fR selects which one of the three possible GC's: | |
522 | TK_3D_FLAT_GC returns the context used for flat surfaces, | |
523 | TK_3D_LIGHT_GC returns the context for light shadows, | |
524 | and TK_3D_DARK_GC returns the context for dark shadows. | |
525 | .PP | |
526 | .VS 8.1 | |
527 | When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR | |
528 | or \fBTk_Free3DBorder\fR should | |
529 | be called to release the resources associated with it. | |
530 | For \fBTk_Free3DBorderFromObj\fR the border to release is specified | |
531 | with the window and color name used to create the | |
532 | border; for \fBTk_Free3DBorder\fR the border to release is specified | |
533 | with the Tk_3DBorder token for the border. | |
534 | There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or | |
535 | \fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR | |
536 | or \fBTk_Get3DBorder\fR. | |
537 | .VE | |
538 | ||
539 | .SH KEYWORDS | |
540 | 3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect |