Tk_Get3DBorder 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. 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 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 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).
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 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 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 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_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; 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 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.
Copyright © 1990-1993 The Regents of the University of California. Copyright © 1994-1996 Sun Microsystems, Inc. Copyright © 1995, 1996 Roger E. Critchlow Jr.