'\"
'\" Copyright 1990 Regents of the University of California
'\" Permission to use, copy, modify, and distribute this
'\" documentation for any purpose and without fee is hereby
'\" granted, provided that this notice appears in all copies.
'\" The University of California makes no representations about
'\" the suitability of this material for any purpose.  It is
'\" provided "as is" without express or implied warranty.
'\" 
'\" $Header: /rel/cvsfiles/unsupported/latest/tk/doc/3DBorder.3,v 1.1 1993/01/24 04:57:10 zoo Exp $ SPRITE (Berkeley)
'\" 
.\" The definitions below are for supplemental macros used in Sprite
.\" manual entries.
.\"
.\" .HS name section [date [version]]
.\"	Replacement for .TH in other man pages.  See below for valid
.\"	section names.
.\"
.\" .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.
.\"
.\" .VS
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
'\"	# Heading for Sprite man pages
.de HS
.if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
.if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
.if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
.if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
.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
.\}
.ie !"\\$3"" \{\
.ta \\n()Au \\n()Bu
\&\\$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
..
'\"	# 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
.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 .5
..
.HS Tk_Get3DBorder tk
.BS
.SH NAME
Tk_Get3DBorder, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_Free3DBorder \- draw borders with three-dimensional appearance
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_3DBorder
\fBTk_Get3DBorder(\fIinterp, tkwin, colorMap, colorName\fB)\fR
.sp
void
\fBTk_Draw3DRectangle(\fIdisplay, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
.sp
void
\fBTk_Fill3DRectangle(\fIdisplay, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
.sp
void
\fBTk_Draw3DPolygon(\fIdisplay, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
.sp
void
\fBTk_Fill3DPolygon(\fIdisplay, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
.sp
void
\fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR
.sp
char *
\fBTk_NameOf3DBorder(\fIborder\fB)\fR
.sp
.VS
XColor *
\fBTk_3DBorderColor(\fIborder\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 in which border will be drawn.
.AP Colormap colormap in
Colormap from which to allocate colors.  If None, then the default
colormap for \fItkwin\fR's screen is used.
.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 Display *display in
Xlib pointer indicating display with which drawable is associated.
.AP Drawable drawable in
X token for window or pixmap;  indicates where border is to be drawn.
.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.
.AP int y in
Y-coordinate of upper-left corner of rectangle describing border.
.AP int width in
Width of rectangle describing border, in pixels.
.AP int height in
Height of rectangle describing border, 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 rectangle relative to exterior;
should be  TK_RELIEF_RAISED or TK_RELIEF_SUNKEN (may also be TK_RELIEF_FLAT
for \fBTk_Fill3DRectangle).
.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.
.AP int leftRelief in
Height of left side of polygon's path relative to right.  TK_RELIEF_RAISED
means left side should appear higher, TK_RELIEF_SUNKEN means right side
should appear higher.  For \fBTk_Fill3DPolygon\fR, TK_RELIEF_FLAT
may also be specified to indicate no difference in height.
.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 \fIcolormap\fR argument
specifies a Colormap to use for allocating colors, and 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 \fIdisplay\fR and \fIdrawable\fR
arguments specify a window or pixmap in which the border is to be
drawn.  \fIDrawable\fR need not refer to the same window as the
\fItkwin\fR used to create the border, but it must refer to a compatible
pixmap or window:  one associated with the same display and with the
same depth as the \fItkwin\fR used to create the border.
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 two 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.
.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_RAISED means the interior of the rectangle should
appear higher than the exterior;  TK_RELIEF_SUNKEN means the reverse;
and TK_RELIEF_FLAT means no border should be drawn at all (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.  If the trajectory contains only
two points, then the result will be a groove or ridge, depending
on whether \fIleftRelief\fR is TK_RELIEF_RAISED or
TK_RELIEF_SUNKEN (respectively).
.PP
\fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR as
\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 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
.VS
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.
.VE
.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
