diff options
Diffstat (limited to 'tcl/doc/3DBorder.3')
| -rw-r--r-- | tcl/doc/3DBorder.3 | 305 |
1 files changed, 0 insertions, 305 deletions
diff --git a/tcl/doc/3DBorder.3 b/tcl/doc/3DBorder.3 deleted file mode 100644 index e57dfef0cff..00000000000 --- a/tcl/doc/3DBorder.3 +++ /dev/null @@ -1,305 +0,0 @@ -'\" -'\" Copyright (c) 1990-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1998 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures" -.BS -.SH 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 -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -.VS 8.1 -Tk_3DBorder -\fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR -.sp -Tk_3DBorder -\fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR -.sp -Tk_3DBorder -\fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR -.VE -.sp -void -\fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR -.sp -void -\fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR -.sp -void -\fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR -.sp -void -\fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR -.sp -void -\fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR -.sp -void -\fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR -.sp -void -\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR -.sp -CONST char * -\fBTk_NameOf3DBorder(\fIborder\fB)\fR -.sp -XColor * -\fBTk_3DBorderColor(\fIborder\fB)\fR -.sp -GC * -\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR -.sp -.VS 8.1 -\fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR -.VE -.sp -\fBTk_Free3DBorder(\fIborder\fB)\fR -.SH ARGUMENTS -.AS "Tk_3DBorder" borderWidth -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tk_Window tkwin in -Token for window (for all procedures except \fBTk_Get3DBorder\fR, -must be the window for which the border was allocated). -.AP Tcl_Obj *objPtr in -.VS 8.1 -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. -.AP char *colorName in -Same as \fIobjPtr\fR except value is supplied as a string rather -than an object. -.VE -.AP Drawable drawable in -X token for window or pixmap; indicates where graphics are to be drawn. -Must either be the X window for \fItkwin\fR or a pixmap with the -same screen and depth as \fItkwin\fR. -.AP Tk_3DBorder border in -Token for border previously allocated in call to \fBTk_Get3DBorder\fR. -.AP int x in -X-coordinate of upper-left corner of rectangle describing border -or bevel, in pixels. -.AP int y in -Y-coordinate of upper-left corner of rectangle describing border or -bevel, in pixels. -.AP int width in -Width of rectangle describing border or bevel, in pixels. -.AP int height in -Height of rectangle describing border or bevel, in pixels. -.AP int borderWidth in -Width of border in pixels. Positive means border is inside rectangle -given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means -border is outside rectangle. -.AP 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 \fBTk_Fill3DRectangle\fR). -.AP 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). -.AP int numPoints in -Number of points at \fI*pointPtr\fR. -.AP int polyBorderWidth in -Width of border in pixels. If positive, border is drawn to left of -trajectory given by \fIpointPtr\fR; if negative, border is drawn to -right of trajectory. If \fIleftRelief\fR is TK_RELIEF_GROOVE or -TK_RELIEF_RIDGE then the border is centered on the trajectory. -.AP 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 \fBTk_Fill3DPolygon\fR, TK_RELIEF_FLAT may also be specified to -indicate no difference in height. -.AP int leftBevel in -Non-zero means this bevel forms the left side of the object; zero means -it forms the right side. -.AP 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. -.AP 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. -.AP int topBevel in -Non-zero means this bevel forms the top side of the object; zero means -it forms the bottom side. -.AP 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. -.BE - -.SH DESCRIPTION -.PP -These procedures provide facilities for drawing window borders in a -way that produces a three-dimensional appearance. -.VS 8.1 -\fBTk_Alloc3DBorderFromObj\fR -allocates colors and Pixmaps needed to draw a border in the window -given by the \fItkwin\fR argument. The value of \fIobjPtr\fR -is a standard Tk color name that determines the border colors. -The color indicated by \fIobjPtr\fR 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 \fIobjPtr\fR, and the shadowed portions of the border will appear -darker than \fIobjPtr\fR. -.PP -\fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls -to \fBTk_Draw3DRectangle\fR. 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 \fIinterp->result\fR. -If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches -information about the return value in \fIobjPtr\fR, which speeds up -future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR -and \fItkwin\fR. -.PP -\fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except -that the color is specified with a string instead of an object. This -prevents \fBTk_Get3DBorder\fR from caching the return value, so -\fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR. -.PP -\fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given -the window and color name used to create the border. -\fBTk_Get3DBorderFromObj\fR doesn't actually create the border; it must -already have been created with a previous call to -\fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. The return -value is cached in \fIobjPtr\fR, which speeds up -future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR -and \fItkwin\fR. -.VE -.PP -Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be -invoked to draw the border. -The \fItkwin\fR argument specifies the -window for which the border was allocated, and \fIdrawable\fR -specifies a window or pixmap in which the border is to be drawn. -\fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it -must refer to a compatible -pixmap or window: one associated with the same screen and with the -same depth as \fItkwin\fR. -The \fIx\fR, \fIy\fR, \fIwidth\fR, and -\fIheight\fR arguments define the bounding box of the border region -within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and -\fIwidth\fR and \fIheight\fR are the dimensions of the window), and -\fIborderWidth\fR specifies the number of pixels actually -occupied by the border. The \fIrelief\fR 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. -.PP -\fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except -that it first fills the rectangular area with the background color -(one corresponding -to the color used to create \fIborder\fR). Then it calls -\fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of -the rectangular area. The argument \fIrelief\fR 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). -.PP -The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex -shapes with a three-dimensional appearance. The \fIpointPtr\fR and -\fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR -indicates how wide the border should be (and on which side of the -trajectory to draw it), and \fIleftRelief\fR indicates which side -of the trajectory should appear raised. \fBTk_Draw3DPolygon\fR -draws a border around the given trajectory using the colors from -\fIborder\fR 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. -.PP -\fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what -\fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR: it fills -the polygonal area with the background color from \fIborder\fR, -then calls \fBTk_Draw3DPolygon\fR to draw a border around the -area (unless \fIleftRelief\fR is TK_RELIEF_FLAT; in this case no -border is drawn). -.PP -The procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fR -provide lower-level drawing primitives that are used by -procedures such as \fBTk_Draw3DRectangle\fR. -These procedures are also useful in their own right for drawing -rectilinear border shapes. -\fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as the -left or right side of a rectangle, and \fBTk_3DHorizontalBevel\fR -draws a horizontal beveled edge, such as the top or bottom of a -rectangle. -Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR -arguments that describe the rectangular area of the beveled edge -(e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR). -The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the -position of the border relative to the ``inside'' of the object, and -\fIrelief\fR indicates the relief of the inside of the object relative -to the outside. -\fBTk_3DVerticalBevel\fR just draws a rectangular region. -\fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate -mitered corners; it should be called after \fBTk_3DVerticalBevel\fR -(otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering in -the corner). -The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fR -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 \fIleftIn\fR and \fIrightIn\fR, and the -bottom bevel should be drawn with 0 for both arguments. -.PP -The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background -pixel and/or pixmap of \fItkwin\fR to produce a result compatible -with \fIborder\fR. For color displays, the resulting background will -just be the color specified when \fIborder\fR 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. -.PP -Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR -will return the color name that was used to create the border. -.PP -The procedure \fBTk_3DBorderColor\fR returns the XColor structure -that will be used for flat surfaces drawn for its \fIborder\fR -argument by procedures like \fBTk_Fill3DRectangle\fR. -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 \fIborder\fR exists. -.PP -The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts -that are used to draw the border. -The argument \fIwhich\fR 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. -.PP -.VS 8.1 -When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR -or \fBTk_Free3DBorder\fR should -be called to release the resources associated with it. -For \fBTk_Free3DBorderFromObj\fR the border to release is specified -with the window and color name used to create the -border; for \fBTk_Free3DBorder\fR the border to release is specified -with the Tk_3DBorder token for the border. -There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or -\fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR -or \fBTk_Get3DBorder\fR. -.VE - -.SH KEYWORDS -3D, background, border, color, depressed, illumination, object, polygon, raised, shadow, three-dimensional effect |