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-
13       dimensional 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
63                                             reporting.
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  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
77       char *colorName (in)                  Same  as  objPtr  except value is
78                                             supplied as a string rather  than
79                                             an object.
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
86                                             tkwin.
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 object 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
121       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
127       int numPoints (in)                    Number of points at *pointPtr.
128
129       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
138       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
151       int leftBevel (in)                    Non-zero  means  this bevel forms
152                                             the  left  side  of  the  object;
153                                             zero  means  it  forms  the right
154                                             side.
155
156       int leftIn (in)                       Non-zero means that the left edge
157                                             of  the  horizontal  bevel angles
158                                             in, so that  the  bottom  of  the
159                                             edge is farther to the right than
160                                             the top.   Zero  means  the  edge
161                                             angles out, so that the bottom is
162                                             farther to the left than the top.
163
164       int rightIn (in)                      Non-zero  means  that  the  right
165                                             edge   of  the  horizontal  bevel
166                                             angles in, so that the bottom  of
167                                             the  edge  is farther to the left
168                                             than the  top.   Zero  means  the
169                                             edge angles out, so that the bot‐
170                                             tom is farther to the right  than
171                                             the top.
172
173       int topBevel (in)                     Non-zero  means  this bevel forms
174                                             the top side of the object;  zero
175                                             means it forms the bottom side.
176
177       int which (in)                        Specifies  which  of the border's
178                                             graphics  contexts  is   desired.
179                                             Must       be      TK_3D_FLAT_GC,
180                                             TK_3D_LIGHT_GC, or TK_3D_DARK_GC.
181_________________________________________________________________
182
183

DESCRIPTION

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

KEYWORDS

313       3D, background, border, color, depressed, illumination,  object,  poly‐
314       gon, raised, shadow, three-dimensional effect
315
316
317
318Tk                                    8.1           Tk_Alloc3DBorderFromObj(3)
Impressum