About Us Documentation

Contact Site Map
 

  

WinPak
Documentation

Tk_3DHorizontalBevel





Tk_Get3DBorder(3)     Tk Library Procedures                   4.0



_________________________________________________________________

NAME

Tk_Get3DBorder,   Tk_Draw3DRectangle,    Tk_Fill3DRectangle,
     Tk_Draw3DPolygon,    Tk_Fill3DPolygon,   Tk_3DVerticalBevel,
     Tk_3DHorizontalBevel,            Tk_SetBackgroundFromBorder,
     Tk_NameOf3DBorder,      Tk_3DBorderColor,     Tk_3DBorderGC,
     Tk_Free3DBorder  -  draw  borders   with   three-dimensional
     appearance

SYNOPSIS

#include <tk.h>

     Tk_3DBorder
     Tk_Get3DBorder(interp, tkwin, colorName)

     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)

     Tk_Free3DBorder(border)

ARGUMENTS

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




Tk                                                              1






Tk_Get3DBorder(3)     Tk Library Procedures                   4.0



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

     Tk_Uid        colorName     (in)      Textual description of
                                           color corresponding to
                                           background       (flat
                                           areas).    Illuminated
                                           edges will be brighter
                                           than this and shadowed
                                           edges will  be  darker
                                           than this.

     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.

     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



Tk                                                              2






Tk_Get3DBorder(3)     Tk Library Procedures                   4.0



                                           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
                                           isn't).

     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
                                           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



Tk                                                              3






Tk_Get3DBorder(3)     Tk Library Procedures                   4.0



                                           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
                                           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                                                              4






Tk_Get3DBorder(3)     Tk Library Procedures                   4.0



                                           TK_3D_DARK_GC.
_________________________________________________________________


DESCRIPTION

These procedures provide facilities for drawing window bord-
     ers  in  a way that produces a three-dimensional appearance.
     Tk_Get3DBorder allocates colors and Pixmaps needed to draw a
     border  in  the  window  given  by  the tkwin argument.  The
     colorName argument indicates what colors should be  used  in
     the  border.   ColorName  may  be  any  value  acceptable to
     Tk_GetColor.  The color  indicated  by  colorName  will  not
     actually be used in the border;  it indicates the background
     color for the window (i.e. a color for flat surfaces).   The
     illuminated portions of the border will appear brighter than
     indicated by colorName, and the  shadowed  portions  of  the
     border will appear darker than colorName.

     Tk_Get3DBorder returns a token that may  be  used  in  later
     calls to Tk_Draw3DRectangle.  If an error occurs in allocat-
     ing information for the border (e.g. colorName isn't a legal
     color specifier), then NULL is returned and an error message
     is left in interp->result.

     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 colorName 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).



Tk                                                              5






Tk_Get3DBorder(3)     Tk Library Procedures                   4.0



     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 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 given by the colorName
     argument passed to Tk_Get3DBorder when border  was  created;



Tk                                                              6






Tk_Get3DBorder(3)     Tk Library Procedures                   4.0



     for  monochrome displays, the resulting background will be a
     light stipple pattern, in order  to  distinguish  the  back-
     ground from the illuminated portion of the border.

     Given a token for a border, the procedure  Tk_NameOf3DBorder
     will   return  the  colorName  string  that  was  passed  to
     Tk_Get3DBorder 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 colorName passed to Tk_Get3DBorder.
     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_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_Free3DBorder should be
     called  to release the resources associated with the border.
     There should be exactly one call to Tk_Free3DBorder for each
     call to Tk_Get3DBorder.


KEYWORDS

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
























Tk                                                              7



Prepared by Ready-to-Run Software, Inc. 

To return to the Ready-to-Run Software Super ReadyPak Table of contents please presshere

 

Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002