DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tk_Get3DBorder(3tk)





Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)


_________________________________________________________________


NAME

     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


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)

     const char *
     Tk_NameOf3DBorder(border)

     XColor *
     Tk_3DBorderColor(border)

     GC *

Tk                      Last change: 8.1                        1


Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)


     Tk_3DBorderGC(tkwin, border, which)

     Tk_Free3DBorderFromObj(tkwin, objPtr)

     Tk_Free3DBorder(border)


ARGUMENTS

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

     Tk_Window tkwin (in)                  Token for window  (for
                                           all  procedures except
                                           Tk_Get3DBorder,   must
                                           be   the   window  for
                                           which the  border  was
                                           allocated).

     Tcl_Obj *objPtr (in)                  Pointer   to    object
                                           whose  value describes
                                           color corresponding to
                                           background       (flat
                                           areas).    Illuminated
                                           edges will be brighter
                                           than this and shadowed
                                           edges  will  be darker
                                           than this.

     char *colorName (in)                  Same as objPtr  except
                                           value is supplied as a
                                           string rather than  an
                                           object.

     Drawable drawable (in)                X token for window  or
                                           pixmap;      indicates
                                           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  pre-
                                           viously  allocated  in
                                           call                to
                                           Tk_Get3DBorder.

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

Tk                      Last change: 8.1                        2


Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)


     int y (in)                            Y-coordinate        of
                                           upper-left  corner  of
                                           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  rec-
                                           tangle  given by x, y,
                                           width,  height,  nega-
                                           tive  means  border is
                                           outside rectangle.

     int relief (in)                       Indicates 3-D position
                                           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 is
                                           not).

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

     int polyBorderWidth (in)              Width  of  border   in
                                           pixels.   If positive,
                                           border  is  drawn   to
                                           left   of   trajectory
                                           given by pointPtr;  if

Tk                      Last change: 8.1                        3


Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)


                                           negative,   border  is
                                           drawn to right of tra-
                                           jectory.   If  leftRe-
                                           lief                is
                                           TK_RELIEF_GROOVE    or
                                           TK_RELIEF_RIDGE   then
                                           the border is centered
                                           on the trajectory.

     int leftRelief (in)                   Height of left side of
                                           polygon's  path  rela-
                                           tive     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_Fill3DPolygon,
                                           TK_RELIEF_FLAT     may
                                           also be  specified  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  bot-
                                           tom  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 edge  is
                                           farther  to  the  left
                                           than  the  top.   Zero

Tk                      Last change: 8.1                        4


Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)


                                           means  the edge angles
                                           out, so that the  bot-
                                           tom  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 graphics con-
                                           texts   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 bord-
     ers  in  a way that produces a three-dimensional appearance.
     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  deter-
     mines the border colors.  The color indicated by objPtr will
     not actually be used in the border;  it indicates the  back-
     ground  color  for  the  window  (i.e. a color for flat sur-
     faces).  The illuminated portions 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  successfully,
     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,  given  the window and color name used to create the
     border.  Tk_Get3DBorderFromObj does not actually create  the
     border;  it  must  already have been created with a previous

Tk                      Last change: 8.1                        5


Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)


     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_Draw3DRectangle
     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 indi-
     cates 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 rectan-
     gle,  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 com-
     plex   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-intersecting, 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
     polygonal area with the background color from  border,  then
     calls  Tk_Draw3DPolygon  to  draw  a  border around the area
     (unless leftRelief is TK_RELIEF_FLAT; in this case no border

Tk                      Last change: 8.1                        6


Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)


     is drawn).

     The procedures Tk_3DVerticalBevel  and  Tk_3DHorizontalBevel
     provide lower-level drawing primitives that are used by pro-
     cedures 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 rectangle, and
     Tk_3DHorizontalBevel draws a horizontal beveled  edge,  such
     as  the  top or bottom of a rectangle.  Each procedure takes
     x, y, width, and height arguments  that  describe  the  rec-
     tangular 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_3DVerticalBevel   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 resulting  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_NameOf3DBorder
     will  return  the  color  name  that  was used to create the
     border.

     The procedure Tk_3DBorderColor returns the XColor  structure
     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
     contexts  that  are  used  to draw the border.  The argument
     which  selects  which  one  of  the  three  possible   GC's:
     TK_3D_FLAT_GC  returns  the  context used for flat surfaces,

Tk                      Last change: 8.1                        7


Tk_Alloc3DBorderFromObj(3Tk Library ProcedureTk_Alloc3DBorderFromObj(3)


     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

Tk                      Last change: 8.1                        8


Man(1) output converted with man2html