1Tk_Alloc3DBorderFromObj(3)   Tk Library Procedures  Tk_Alloc3DBorderFromObj(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

16       #include <tk.h>
17
18       Tk_3DBorder
19       Tk_Alloc3DBorderFromObj(interp, tkwin, objPtr)
20
21       Tk_3DBorder
22       Tk_Get3DBorder(interp, tkwin, colorName)
23
24       Tk_3DBorder
25       Tk_Get3DBorderFromObj(tkwin, objPtr)
26
27       void
28       Tk_Draw3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)
29
30       void
31       Tk_Fill3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)
32
33       void
34       Tk_Draw3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)
35
36       void
37       Tk_Fill3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)
38
39       void
40       Tk_3DVerticalBevel(tkwin, drawable, border, x, y, width, height, leftBevel, relief)
41
42       void
43       Tk_3DHorizontalBevel(tkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief)
44
45       void
46       Tk_SetBackgroundFromBorder(tkwin, border)
47
48       const char *
49       Tk_NameOf3DBorder(border)
50
51       XColor *
52       Tk_3DBorderColor(border)
53
54       GC *
55       Tk_3DBorderGC(tkwin, border, which)
56
57       Tk_Free3DBorderFromObj(tkwin, objPtr)
58
59       Tk_Free3DBorder(border)
60

ARGUMENTS

62       Tcl_Interp *interp (in)               Interpreter to use for error  re‐
63                                             porting.
64
65       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
70       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
77       char *colorName (in)                  Same  as  objPtr  except value is
78                                             supplied as a string rather  than
79                                             a value.
80
81       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
88       Tk_3DBorder border (in)               Token for border previously allo‐
89                                             cated in call to Tk_Get3DBorder.
90
91       int x (in)                            X-coordinate of upper-left corner
92                                             of rectangle describing border or
93                                             bevel, in pixels.
94
95       int y (in)                            Y-coordinate of upper-left corner
96                                             of rectangle describing border or
97                                             bevel, in pixels.
98
99       int width (in)                        Width   of  rectangle  describing
100                                             border or bevel, in pixels.
101
102       int height (in)                       Height  of  rectangle  describing
103                                             border or bevel, in pixels.
104
105       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
111       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
120       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
126       int numPoints (in)                    Number of points at *pointPtr.
127
128       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
137       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
149       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
153       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
161       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
170       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
174       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

DESCRIPTION

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
192       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
200       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
205       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
212       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
229       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
237       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
248       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
254       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
276       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
283       Given a token for a border, the procedure Tk_NameOf3DBorder will return
284       the color name that was used to create the border.
285
286       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
292       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
298       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

KEYWORDS

308       3D, background, border, color, depressed, illumination, value, polygon,
309       raised, shadow, three-dimensional effect
310
311
312
313Tk                                    8.1           Tk_Alloc3DBorderFromObj(3)
Impressum