diff options
Diffstat (limited to 'tk/doc/3DBorder.3')
| -rw-r--r-- | tk/doc/3DBorder.3 | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/tk/doc/3DBorder.3 b/tk/doc/3DBorder.3 new file mode 100644 index 00000000000..2916e8e1d2c --- /dev/null +++ b/tk/doc/3DBorder.3 @@ -0,0 +1,262 @@ +'\" +'\" Copyright (c) 1990-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 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_Get3DBorder 3 4.0 Tk "Tk Library Procedures" +.BS +.SH 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 +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_3DBorder +\fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR +.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 +char * +\fBTk_NameOf3DBorder(\fIborder\fB)\fR +.sp +XColor * +\fBTk_3DBorderColor(\fIborder\fB)\fR +.sp +GC * +\fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR +.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 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. +.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. \fBTk_Get3DBorder\fR +allocates colors and Pixmaps needed to draw a border in the window +given by the \fItkwin\fR argument. The \fIcolorName\fR +argument indicates what colors should be used in the border. +\fIColorName\fR may be any value acceptable to \fBTk_GetColor\fR. +The color indicated by \fIcolorName\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 \fIcolorName\fR, and the shadowed portions of the border will appear +darker than \fIcolorName\fR. +.PP +\fBTk_Get3DBorder\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. \fIcolorName\fR isn't a legal color specifier), +then NULL is returned and an error message is left in \fIinterp->result\fR. +.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 \fIcolorName\fR 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 given by the \fIcolorName\fR argument passed to +\fBTk_Get3DBorder\fR 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 \fIcolorName\fR string that was passed to +\fBTk_Get3DBorder\fR 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 \fIcolorName\fR passed to +\fBTk_Get3DBorder\fR. +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 +When a border is no longer needed, \fBTk_Free3DBorder\fR should +be called to release the resources associated with the border. +There should be exactly one call to \fBTk_Free3DBorder\fR for +each call to \fBTk_Get3DBorder\fR. + +.SH KEYWORDS +3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect |