'\" '\" 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. '\" .TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. .\" type is type of argument (int, etc.), in/out is either "in", "out", .\" or "in/out" to describe whether procedure reads or modifies arg, .\" and indent is equivalent to second arg of .IP (shouldn't ever be .\" needed; use .AS below instead) .\" .\" .AS ?type? ?name? .\" Give maximum sizes of arguments for setting tab stops. Type and .\" name are examples of largest possible arguments that will be passed .\" to .AP later. If args are omitted, default tab stops are used. .\" .\" .BS .\" Start box enclosure. From here until next .BE, everything will be .\" enclosed in one large box. .\" .\" .BE .\" End of box enclosure. .\" .\" .CS .\" Begin code excerpt. .\" .\" .CE .\" End code excerpt. .\" .\" .VS ?version? ?br? .\" Begin vertical sidebar, for use in marking newly-changed parts .\" of man pages. The first argument is ignored and used for recording .\" the version when the .VS was added, so that the sidebars can be .\" found and removed when they reach a certain age. If another argument .\" is present, then a line break is forced before starting the sidebar. .\" .\" .VE .\" End of vertical sidebar. .\" .\" .DS .\" Begin an indented unfilled display. .\" .\" .DE .\" End of indented unfilled display. .\" .\" .SO ?manpage? .\" Start of list of standard options for a Tk widget. The manpage .\" argument defines where to look up the standard options; if .\" omitted, defaults to "options". The options follow on successive .\" lines, in three columns separated by tabs. .\" .\" .SE .\" End of list of standard options for a Tk widget. .\" .\" .OP cmdName dbName dbClass .\" Start of description of a specific option. cmdName gives the .\" option's name as specified in the class command, dbName gives .\" the option's name in the option database, and dbClass gives .\" the option's class in the option database. .\" .\" .UL arg1 arg2 .\" Print arg1 underlined, then print arg2 normally. .\" .\" .QW arg1 ?arg2? .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). .\" .\" .PQ arg1 ?arg2? .\" Print an open parenthesis, arg1 in quotes, then arg2 normally .\" (for trailing punctuation) and then a closing parenthesis. .\" .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. .if t .wh -1.3i ^B .nr ^l \n(.l .ad b .\" # Start an argument description .de AP .ie !"\\$4"" .TP \\$4 .el \{\ . ie !"\\$2"" .TP \\n()Cu . el .TP 15 .\} .ta \\n()Au \\n()Bu .ie !"\\$3"" \{\ \&\\$1 \\fI\\$2\\fP (\\$3) .\".b .\} .el \{\ .br .ie !"\\$2"" \{\ \&\\$1 \\fI\\$2\\fP .\} .el \{\ \&\\fI\\$1\\fP .\} .\} .. .\" # define tabbing values for .AP .de AS .nr )A 10n .if !"\\$1"" .nr )A \\w'\\$1'u+3n .nr )B \\n()Au+15n .\" .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n .nr )C \\n()Bu+\\w'(in/out)'u+2n .. .AS Tcl_Interp Tcl_CreateInterp in/out .\" # BS - start boxed text .\" # ^y = starting y location .\" # ^b = 1 .de BS .br .mk ^y .nr ^b 1u .if n .nf .if n .ti 0 .if n \l'\\n(.lu\(ul' .if n .fi .. .\" # BE - end boxed text (draw box now) .de BE .nf .ti 0 .mk ^t .ie n \l'\\n(^lu\(ul' .el \{\ .\" Draw four-sided box normally, but don't draw top of .\" box if the box started on an earlier page. .ie !\\n(^b-1 \{\ \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .el \}\ \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .\} .fi .br .nr ^b 0 .. .\" # VS - start vertical sidebar .\" # ^Y = starting y location .\" # ^v = 1 (for troff; for nroff this doesn't matter) .de VS .if !"\\$2"" .br .mk ^Y .ie n 'mc \s12\(br\s0 .el .nr ^v 1u .. .\" # VE - end of vertical sidebar .de VE .ie n 'mc .el \{\ .ev 2 .nf .ti 0 .mk ^t \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' .sp -1 .fi .ev .\} .nr ^v 0 .. .\" # Special macro to handle page bottom: finish off current .\" # box/sidebar if in box/sidebar mode, then invoked standard .\" # page bottom macro. .de ^B .ev 2 'ti 0 'nf .mk ^t .if \\n(^b \{\ .\" Draw three-sided box if this is the box's first page, .\" draw two sides but no top otherwise. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .\} .if \\n(^v \{\ .nr ^x \\n(^tu+1v-\\n(^Yu \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c .\} .bp 'fi .ev .if \\n(^b \{\ .mk ^y .nr ^b 2 .\} .if \\n(^v \{\ .mk ^Y .\} .. .\" # DS - begin display .de DS .RS .nf .sp .. .\" # DE - end display .de DE .fi .RE .sp .. .\" # SO - start of list of standard options .de SO 'ie '\\$1'' .ds So \\fBoptions\\fR 'el .ds So \\fB\\$1\\fR .SH "STANDARD OPTIONS" .LP .nf .ta 5.5c 11c .ft B .. .\" # SE - end of list of standard options .de SE .fi .ft R .LP See the \\*(So manual entry for details on the standard options. .. .\" # OP - start of full description for a single option .de OP .LP .nf .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi .IP .. .\" # CS - begin code excerpt .de CS .RS .nf .ta .25i .5i .75i 1i .. .\" # CE - end code excerpt .de CE .fi .RE .. .\" # UL - underline word .de UL \\$1\l'|0\(ul'\\$2 .. .\" # QW - apply quotation marks to word .de QW .ie '\\*(lq'"' ``\\$1''\\$2 .\"" fix emacs highlighting .el \\*(lq\\$1\\*(rq\\$2 .. .\" # PQ - apply parens and quotation marks to word .de PQ .ie '\\*(lq'"' (``\\$1''\\$2)\\$3 .\"" fix emacs highlighting .el (\\*(lq\\$1\\*(rq\\$2)\\$3 .. .\" # QR - quoted range .de QR .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 .\"" fix emacs highlighting .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 .. .\" # MT - "empty" string .de MT .QW "" .. .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 \fR Tk_3DBorder \fBTk_Alloc3DBorderFromObj\fR(\fIinterp, tkwin, objPtr\fR) .sp Tk_3DBorder \fBTk_Get3DBorder\fR(\fIinterp, tkwin, colorName\fR) .sp Tk_3DBorder \fBTk_Get3DBorderFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_Draw3DRectangle\fR(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fR) .sp \fBTk_Fill3DRectangle\fR(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fR) .sp \fBTk_Draw3DPolygon\fR(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fR) .sp \fBTk_Fill3DPolygon\fR(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fR) .sp \fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fR) .sp \fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fR) .sp \fBTk_SetBackgroundFromBorder\fR(\fItkwin, border\fR) .sp const char * \fBTk_NameOf3DBorder\fR(\fIborder\fR) .sp XColor * \fBTk_3DBorderColor\fR(\fIborder\fR) .sp GC * \fBTk_3DBorderGC\fR(\fItkwin, border, which\fR) .sp \fBTk_Free3DBorderFromObj\fR(\fItkwin, objPtr\fR) .sp \fBTk_Free3DBorder\fR(\fIborder\fR) .fi .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 Pointer to value 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 "const char" *colorName in Same as \fIobjPtr\fR except value is supplied as a string rather than a value. .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 value relative to exterior; should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR, \fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR (may also be \fBTK_RELIEF_FLAT\fR 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 is not). .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 \fBTK_RELIEF_GROOVE\fR or \fBTK_RELIEF_RIDGE\fR then the border is centered on the trajectory. .AP int leftRelief in Height of left side of polygon's path relative to right. \fBTK_RELIEF_RAISED\fR means left side should appear higher and \fBTK_RELIEF_SUNKEN\fR means right side should appear higher; \fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean the obvious things. For \fBTk_Fill3DPolygon\fR, \fBTK_RELIEF_FLAT\fR 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 value; 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 value; zero means it forms the bottom side. .AP int which in Specifies which of the border's graphics contexts is desired. Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR. .BE .SH DESCRIPTION .PP These procedures provide facilities for drawing window borders in a way that produces a three-dimensional appearance. \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 as the result of interpreter \fIinterp\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 a value. 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 does not 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. .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: \fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should appear raised relative to the exterior of the rectangle, and \fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed. \fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR 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 (\fBTK_RELIEF_FLAT\fR 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 \fBTK_RELIEF_FLAT\fR; 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 .QW inside of the value, and \fIrelief\fR indicates the relief of the inside of the value 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: \fBTK_3D_FLAT_GC\fR returns the context used for flat surfaces, \fBTK_3D_LIGHT_GC\fR returns the context for light shadows, and \fBTK_3D_DARK_GC\fR returns the context for dark shadows. .PP 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. .SH KEYWORDS 3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect