Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tk_Alloc3DBorderFromObj(3)                  Tk Library Procedures                 Tk_Alloc3DBorderFromObj(3)



____________________________________________________________________________________________________________

NAME
       Tk_Alloc3DBorderFromObj,  Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectan-gle, Tk_Fill3DRectangle,
       gle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel,  Tk_SetBackground-FromBorder, Tk_SetBackgroundFromBorder,
       FromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBor-der Tk_Free3DBorder
       der - 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_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 previously allocated in call  to  Tk_Get3DBor-der. Tk_Get3DBorder.
                                             der.

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

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

       int relief (in)                       Indicates  3-D position of interior of object relative to exte-rior; exterior;
                                             rior;    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 negative, border is
                                             drawn   to   right   of   trajectory.    If    leftRelief    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  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_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 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 edge  is  farther  to  the
                                             left than 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 graphics 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-dimen-sional three-dimensional
       sional  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 determines
       mines  the border colors.  The color indicated by objPtr 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 por-tions portions
       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  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 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 win-dow window
       dow 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 rectan-gle, rectangle,
       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 rec-tangle. rectangle.
       tangle.

       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-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  bor-der border
       der 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 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 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 argu-ments arguments
       ments 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 rel-ative relative
       ative to the "inside" of the object, and relief indicates the relief of the inside of the object rel-ative relative
       ative  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_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 speci-fied specified
       fied 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-dimen-sional three-dimensional
       sional effect



Tk                                                   8.1                          Tk_Alloc3DBorderFromObj(3)