Subversion Repositories or1k_old

'\"

'\" 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: 3DBorder.3,v 1.1.1.1 2002-01-16 10:25:47 markom Exp $

'\"

.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 \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