NAME

       Tk_Alloc3DBorderFromObj,  Tk_Get3DBorder,  Tk_Get3DBorder­
       FromObj,      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


SYNOPSIS

       #include <tk.h>

       Tk_3DBorder                                                |
       Tk_Alloc3DBorderFromObj(interp, tkwin, objPtr)             |

       Tk_3DBorder                                                |
       Tk_Get3DBorder(interp, tkwin, colorName)                   |

       Tk_3DBorder                                                |
       Tk_Get3DBorderFromObj(tkwin, objPtr)                       |

       void
       Tk_Draw3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)

       void
       Tk_Fill3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)

       void
       Tk_Draw3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)

       void
       Tk_Fill3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)

       void
       Tk_3DVerticalBevel(tkwin, drawable, border, x, y, width, height, leftBevel, relief)

       void
       Tk_3DHorizontalBevel(tkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief)

       void
       Tk_SetBackgroundFromBorder(tkwin, border)

       char *
       Tk_NameOf3DBorder(border)

       XColor *
       Tk_3DBorderColor(border)

       GC *
       Tk_3DBorderGC(tkwin, border, which)



ARGUMENTS

       Tcl_Interp    *interp       (in)      Interpreter  to  use
                                             for error reporting.

       Tk_Window     tkwin         (in)      Token   for   window
                                             (for all  procedures
                                             except  Tk_Get3DBor­
                                             der,  must  be   the
                                             window for which the
                                             border   was   allo­
                                             cated).

       Tcl_Obj       *objPtr       (in)      Pointer   to  object |
                                             whose          value |
                                             describes color cor­ |
                                             responding to  back­ |
                                             ground (flat areas). |
                                             Illuminated    edges |
                                             will   be   brighter |
                                             than this and  shad­ |
                                             owed  edges  will be |
                                             darker than this.    |

       char          *colorName    (in)                                  ||
                                             Same    as    objPtr |
                                             except value is sup­ |
                                             plied  as  a  string |
                                             rather    than    an |
                                             object.

       Drawable      drawable      (in)      X  token  for window
                                             or  pixmap;    indi­
                                             cates where graphics
                                             are  to  be   drawn.
                                             Must either be the X
                                             window for tkwin  or
                                             a  pixmap  with  the
                                             same   screen    and
                                             depth as tkwin.

       Tk_3DBorder   border        (in)      Token   for   border
                                             previously allocated
                                             in      call      to
                                             Tk_Get3DBorder.

       int           x             (in)      X-coordinate      of
                                             upper-left corner of
                                             rectangle describing
                                             border  or bevel, in
                                             pixels.

                                             rectangle describing
                                             border  or bevel, in
                                             pixels.

       int           width         (in)      Width  of  rectangle
                                             describing border or
                                             bevel, in pixels.

       int           height        (in)      Height of  rectangle
                                             describing border or
                                             bevel, in pixels.

       int           borderWidth   (in)      Width of  border  in
                                             pixels.     Positive
                                             means   border    is
                                             inside     rectangle
                                             given   by   x,   y,
                                             width, height, nega­
                                             tive means border is
                                             outside rectangle.

       int           relief        (in)      Indicates  3-D posi­
                                             tion of interior  of
                                             object  relative  to
                                             exterior; should  be
                                             TK_RELIEF_RAISED,
                                             TK_RELIEF_SUNKEN,
                                             TK_RELIEF_GROOVE,
                                             TK_RELIEF_SOLID,  or
                                             TK_RELIEF_RIDGE (may
                                             also              be
                                             TK_RELIEF_FLAT   for
                                             Tk_Fill3DRectangle).

       XPoint        *pointPtr     (in)      Pointer  to array of
                                             points    describing
                                             the  set of vertices
                                             in a  polygon.   The
                                             polygon  need not be
                                             closed (it  will  be
                                             closed automatically
                                             if it isn't).

       int           numPoints     (in)      Number of points  at
                                             *pointPtr.

       int           polyBorderWidth(in)     Width  of  border in
                                             pixels.   If   posi­
                                             tive,    border   is
                                             drawn  to  left   of
                                             trajectory  given by
                                             pointPtr;  if  nega­
                                             trajectory.       If
                                             leftRelief        is
                                             TK_RELIEF_GROOVE  or
                                             TK_RELIEF_RIDGE then
                                             the  border  is cen­
                                             tered on the trajec­
                                             tory.

       int           leftRelief    (in)      Height  of left side
                                             of  polygon's   path
                                             relative  to  right.
                                             TK_RELIEF_RAISED
                                             means    left   side
                                             should appear higher
                                             and TK_RELIEF_SUNKEN
                                             means   right   side
                                             should        appear
                                             higher;
                                             TK_RELIEF_GROOVE and
                                             TK_RELIEF_RIDGE mean
                                             the  obvious things.
                                             For   Tk_Fill3DPoly­
                                             gon,  TK_RELIEF_FLAT
                                             may also  be  speci­
                                             fied  to indicate no
                                             difference        in
                                             height.

       int           leftBevel     (in)      Non-zero  means this
                                             bevel forms the left
                                             side  of the object;
                                             zero means it  forms
                                             the right side.

       int           leftIn        (in)      Non-zero  means that
                                             the left edge of the
                                             horizontal     bevel
                                             angles in,  so  that
                                             the  bottom  of  the
                                             edge is  farther  to
                                             the  right  than the
                                             top.  Zero means the
                                             edge  angles out, so
                                             that the  bottom  is
                                             farther  to the left
                                             than the top.

       int           rightIn       (in)      Non-zero means  that
                                             the  right  edge  of
                                             the horizontal bevel
                                             angles  in,  so that
                                             the  bottom  of  the
                                             top.  Zero means the
                                             edge angles out,  so
                                             that  the  bottom is
                                             farther to the right
                                             than the top.

       int           topBevel      (in)      Non-zero  means this
                                             bevel forms the  top
                                             side  of the object;
                                             zero means it  forms
                                             the bottom side.

       int           which         (in)      Specifies  which  of
                                             the border's  graph­
                                             ics    contexts   is
                                             desired.   Must   be
                                             TK_3D_FLAT_GC,
                                             TK_3D_LIGHT_GC,   or
                                             TK_3D_DARK_GC.
_________________________________________________________________



DESCRIPTION

       These  procedures  provide  facilities  for drawing window
       borders in a way that produces a three-dimensional appear­
       ance.    Tk_Alloc3DBorderFromObj   allocates   colors  and |
       Pixmaps needed to draw a border in the window given by the |
       tkwin  argument.   The  value  of  objPtr is a standard Tk |
       color name that determines the border colors.   The  color |
       indicated  by objPtr will not actually be used in the bor­ |
       der;  it indicates the background  color  for  the  window |
       (i.e.  a  color  for flat surfaces).  The illuminated por­ |
       tions of the border will appear brighter than indicated by |
       objPtr,  and  the  shadowed  portions  of  the border will |
       appear darker than objPtr.                                 |

       Tk_Alloc3DBorderFromObj returns a token that may  be  used |
       in  later calls to Tk_Draw3DRectangle.  If an error occurs |
       in allocating information for the  border  (e.g.  a  bogus |
       color  name  was given) then NULL is returned and an error |
       message is left in interp->result.  If it returns success­ |
       fully,  Tk_Alloc3DBorderFromObj  caches  information about |
       the return value in objPtr, which speeds up  future  calls |
       to Tk_Alloc3DBorderFromObj with the same objPtr and tkwin. |

       Tk_Get3DBorder  is  identical  to  Tk_Alloc3DBorderFromObj |
       except  that  the color is specified with a string instead |
       of an object.  This prevents Tk_Get3DBorder  from  caching |
       the return value, so Tk_Get3DBorder is less efficient than |
       Tk_Alloc3DBorderFromObj.                                   |

       Tk_Get3DBorderFromObj returns the token  for  an  existing |
       border;  it must already have been created with a previous |
       call to Tk_Alloc3DBorderFromObj  or  Tk_Get3DBorder.   The |
       return  value  is cached in objPtr, which speeds up future |
       calls to Tk_Get3DBorderFromObj with the  same  objPtr  and |
       tkwin.

       Once a border structure has been created, Tk_Draw3DRectan­
       gle may be invoked to draw the border.  The tkwin argument
       specifies  the  window for which the border was allocated,
       and drawable specifies a window or  pixmap  in  which  the
       border  is  to  be  drawn.  Drawable need not refer to the
       same window as tkwin, but it must refer  to  a  compatible
       pixmap or window:  one associated with the same screen and
       with the same depth as tkwin.  The x, y, width, and height
       arguments  define  the  bounding  box of the border region
       within drawable (usually x and y are zero  and  width  and
       height  are the dimensions of the window), and borderWidth
       specifies the number of pixels actually  occupied  by  the
       border.   The  relief  argument indicates which of several
       three-dimensional  effects  is  desired:  TK_RELIEF_RAISED
       means  that  the  interior  of the rectangle should appear
       raised relative to the  exterior  of  the  rectangle,  and
       TK_RELIEF_SUNKEN  means  that  the  interior should appear
       depressed.  TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that
       there  should  appear  to  be a groove or ridge around the
       exterior of the rectangle.

       Tk_Fill3DRectangle  is  somewhat  like  Tk_Draw3DRectangle
       except  that  it first fills the rectangular area with the
       background color (one corresponding to the color  used  to
       create  border).  Then it calls Tk_Draw3DRectangle to draw
       a border just inside the outer  edge  of  the  rectangular
       area.   The  argument  relief indicates the desired effect
       (TK_RELIEF_FLAT means no border should be drawn; all  that
       happens  is  to  fill  the  rectangle  with the background
       color).

       The procedure Tk_Draw3DPolygon may be used  to  draw  more
       complex  shapes  with a three-dimensional appearance.  The
       pointPtr and  numPoints  arguments  define  a  trajectory,
       polyBorderWidth  indicates  how  wide the border should be
       (and on which side of the  trajectory  to  draw  it),  and
       leftRelief  indicates  which side of the trajectory should
       appear raised.  Tk_Draw3DPolygon draws a border around the
       given trajectory using the colors from border to produce a
       three-dimensional appearance.  If the trajectory  is  non-
       self-intersecting,  the  appearance  will  be  a raised or
       sunken polygon shape.  The trajectory may  be  self-inter­
       secting, although it's not clear how useful this is.

       Tk_Fill3DPolygon     is     to    Tk_Draw3DPolygon    what
       Tk_Fill3DRectangle is to Tk_Draw3DRectangle:  it fills the
       (unless  leftRelief  is  TK_RELIEF_FLAT;   in this case no
       border is drawn).

       The procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel
       provide  lower-level  drawing  primitives that are used by
       procedures such as Tk_Draw3DRectangle.   These  procedures
       are also useful in their own right for drawing rectilinear
       border  shapes.   Tk_3DVerticalBevel  draws   a   vertical
       beveled  edge, such as the left or right side of a rectan­
       gle, and Tk_3DHorizontalBevel draws a  horizontal  beveled
       edge, such as the top or bottom of a rectangle.  Each pro­
       cedure takes  x,  y,  width,  and  height  arguments  that
       describe  the  rectangular area of the beveled edge (e.g.,
       width is the border width  for  Tk_3DVerticalBevel).   The
       leftBorder  and  topBorder arguments indicate the position
       of the border relative to the ``inside''  of  the  object,
       and  relief  indicates  the  relief  of  the inside of the
       object relative to the outside.   Tk_3DVerticalBevel  just
       draws  a rectangular region.  Tk_3DHorizontalBevel draws a
       trapezoidal region to generate mitered corners;  it should
       be  called after Tk_3DVerticalBevel (otherwise Tk_3DVerti­
       calBevel will overwrite the mitering in the corner).   The
       leftIn   and  rightIn  arguments  to  Tk_3DHorizontalBevel
       describe the mitering at the corners;  a value of 1  means
       that the bottom edge of the trapezoid will be shorter than
       the top, 0 means it will be longer.  For example, to  draw
       a  rectangular border the top bevel should be drawn with 1
       for both leftIn and rightIn, and the bottom  bevel  should
       be drawn with 0 for both arguments.

       The  procedure  Tk_SetBackgroundFromBorder will modify the
       background pixel and/or  pixmap  of  tkwin  to  produce  a
       result  compatible  with  border.  For color displays, the
       resulting background will just be the color specified when
       border  was created;  for monochrome displays, the result­
       ing background will be a light stipple pattern,  in  order
       to distinguish the background from the illuminated portion
       of the border.

       Given a token for a border, the procedure  Tk_NameOf3DBor­
       der will return the color name that was used to create the
       border.

       The procedure Tk_3DBorderColor returns the  XColor  struc­
       ture  that  will  be  used for flat surfaces drawn for its
       border argument  by  procedures  like  Tk_Fill3DRectangle.
       The  return  value  corresponds to the color name that was
       used to create the border.  The XColor, and its associated
       pixel  value,  will  remain  allocated  as  long as border
       exists.

       The procedure Tk_3DBorderGC returns one of the X  graphics
       TK_3D_FLAT_GC  returns the context used for flat surfaces,
       TK_3D_LIGHT_GC returns the context for light shadows,  and
       TK_3D_DARK_GC returns the context for dark shadows.

       When  a border is no longer needed, Tk_Free3DBorderFromObj |
       or  Tk_Free3DBorder  should  be  called  to  release   the |
       resources  associated with it.  For Tk_Free3DBorderFromObj |
       the border to release is specified  with  the  window  and |
       color  name used to create the border; for Tk_Free3DBorder |
       the border to release is specified  with  the  Tk_3DBorder |
       token for the border.  There should be exactly one call to |
       Tk_Free3DBorderFromObj or Tk_Free3DBorder for each call to |
       Tk_Alloc3DBorderFromObj or Tk_Get3DBorder.



KEYWORDS

       3D,  background,  border,  color, depressed, illumination,
       object, polygon, raised, shadow, three-dimensional effect