Manual Pages for UNIX Darwin command on man Tk

Manual Pages for UNIX Darwin command on man Tk_Get3DBorderFromObj

TkAlloc3DBorderFromObj(3) Tk Library Procedures TkAlloc3DBorderFromObj(3)

NAME

TkAlloc3DBorderFromObj, TkGet3DBorder, TkGet3DBorderFromObj, TkDraw3DRectangle, TkFill3DRectangle, TkDraw3DPolygon,

TkFill3DPolygon, Tk3DVerticalBevel, Tk3DHorizontalBevel, TkSetBack-

groundFromBorder, TkNameOf3DBorder, Tk3DBorderColor, Tk3DBorderGC,

TkFree3DBorderFromObj, TkFree3DBorder - draw borders with three-

dimensional appearance

SYNOPSIS

##iinncclluuddee <>

Tk3DBorder | TTkkAAlllloocc33DDBBoorrddeerrFFrroommOObbjj((interp, tkwin, objPtr)) | Tk3DBorder | TTkkGGeett33DDBBoorrddeerr((interp, tkwin, colorName)) | Tk3DBorder | TTkkGGeett33DDBBoorrddeerrFFrroommOObbjj((tkwin, objPtr)) | void TTkkDDrraaww33DDRReeccttaannggllee((tkwin, drawable, border, x, y, width, height, borderWidth, relief)) void TTkkFFiillll33DDRReeccttaannggllee((tkwin, drawable, border, x, y, width, height, borderWidth, relief)) void TTkkDDrraaww33DDPPoollyyggoonn((tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)) void TTkkFFiillll33DDPPoollyyggoonn((tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)) void TTkk33DDVVeerrttiiccaallBBeevveell(tkwin, drawable, border, x, y, width, height, leftBevel, relief)) void TTkk33DDHHoorriizzoonnttaallBBeevveell(tkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief)) void TTkkSSeettBBaacckkggrroouunnddFFrroommBBoorrddeerr((tkwin, border)) CONST char * TTkkNNaammeeOOff33DDBBoorrddeerr((border)) XColor * TTkk33DDBBoorrddeerrCCoolloorr((border)) GC * TTkk33DDBBoorrddeerrGGCC((tkwin, border, which)) TTkkFFrreeee33DDBBoorrddeerrFFrroommOObbjj((tkwin, objPtr)) | TTkkFFrreeee33DDBBoorrddeerr((border)) AARRGGUUMMEENNTTSS TclInterp *interp (in) Interpreter to use for error reporting.

TkWindow tkwin (in) Token for window (for all proce-

dures except TTkkGGeett33DDBBoorrddeerr, must

be the window for which the bor-

der was allocated). TclObj *objPtr (in) Pointer to object whose value | describes color corresponding to |

background (flat areas). Illumi- |

nated edges will be brighter than | this and shadowed edges will be | darker than this. |

char *color- |

Name (in) | | Same as objPtr except value is | supplied as a string rather than | an object. Drawable drawable (in) X token for window or pixmap; indicates where graphics are to be drawn. Must either be the X window for tkwin or a pixmap with the same screen and depth as tkwin.

Tk3DBorder border (in) Token for border previously allo-

cated in call to TTkkGGeett33DDBBoorrddeerr.

int x (in) X-coordinate of upper-left corner

of rectangle describing border or bevel, in pixels.

int y (in) Y-coordinate of upper-left corner

of rectangle describing border or bevel, in pixels. int width (in) Width of rectangle describing border or bevel, in pixels. int height (in) Height of rectangle describing border or bevel, in pixels.

int borderWidth (in) Width of border in pixels. Posi-

tive means border is inside rec-

tangle given by x, y, width, height, negative means border is outside rectangle.

int relief (in) Indicates 3-D position of inte-

rior of object relative to exte-

rior; should be TKRELIEFRAISED, TKRELIEFSUNKEN, TKRELIEFGROOVE, TKRELIEFSOLID, or TKRELIEFRIDGE (may also be

TKRELIEFFLAT for TTkkFFiillll33DDRReecctt-

aannggllee). 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). int numPoints (in) Number of points at *pointPtr. int polyBorderWidth(in) Width of border in pixels. If positive, border is drawn to left of trajectory given by pointPtr; if negative, border is drawn to

right of trajectory. If leftRe-

lief is TKRELIEFGROOVE or TKRELIEFRIDGE then the border is centered on the trajectory. int leftRelief (in) Height of left side of polygon's path relative to right. TKRELIEFRAISED means left side should appear higher and TKRELIEFSUNKEN means right side should appear higher; TKRELIEFGROOVE and TKRELIEFRIDGE mean the obvious things. For TTkkFFiillll33DDPPoollyyggoonn,

TKRELIEFFLAT may also be speci-

fied to indicate no difference in height.

int leftBevel (in) Non-zero means this bevel forms

the left side of the object; zero means it forms the right side.

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.

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 bot-

tom is farther to the right than the top.

int topBevel (in) Non-zero means this bevel forms

the top side of the object; zero means it forms the bottom side. int which (in) Specifies which of the border's graphics contexts is desired. Must be TK3DFLATGC, TK3DLIGHTGC, or TK3DDARKGC.

DESCRIPTION

These procedures provide facilities for drawing window borders in a way

that produces a three-dimensional appearance. TTkkAAlllloocc33DDBBoorrddeerrFFrroommOObbjj |

allocates colors and Pixmaps needed to draw a border in the window | given by the tkwin argument. The value of objPtr is a standard Tk | color name that determines the border colors. The color indicated by |

objPtr will not actually be used in the border; it indicates the back- |

ground color for the window (i.e. a color for flat surfaces). The | illuminated portions of the border will appear brighter than indicated | by objPtr, and the shadowed portions of the border will appear darker | than objPtr. | TTkkAAlllloocc33DDBBoorrddeerrFFrroommOObbjj returns a token that may be used in later calls | to TTkkDDrraaww33DDRReeccttaannggllee. 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 interp->result. If it returns |

successfully, TTkkAAlllloocc33DDBBoorrddeerrFFrroommOObbjj caches information about the |

return value in objPtr, which speeds up future calls to TTkkAAlllloocc33DDBBoorr- |

ddeerrFFrroommOObbjj with the same objPtr and tkwin. | TTkkGGeett33DDBBoorrddeerr is identical to TTkkAAlllloocc33DDBBoorrddeerrFFrroommOObbjj except that the | color is specified with a string instead of an object. This prevents | TTkkGGeett33DDBBoorrddeerr from caching the return value, so TTkkGGeett33DDBBoorrddeerr is less | efficient than TTkkAAlllloocc33DDBBoorrddeerrFFrroommOObbjj. | TTkkGGeett33DDBBoorrddeerrFFrroommOObbjj returns the token for an existing border, given |

the window and color name used to create the border. TTkkGGeett33DDBBoorrddeerr- |

FFrroommOObbjj doesn't actually create the border; it must already have been |

created with a previous call to TTkkAAlllloocc33DDBBoorrddeerrFFrroommOObbjj or TTkkGGeett33DDBBoorr- |

ddeerr. The return value is cached in objPtr, which speeds up future | calls to TTkkGGeett33DDBBoorrddeerrFFrroommOObbjj with the same objPtr and tkwin. Once a border structure has been created, TTkkDDrraaww33DDRReeccttaannggllee may be invoked to draw the border. The tkwin argument specifies the window for which the border was allocated, and drawable specifies a window or pixmap in which the border is to be drawn. Drawable need not refer to the same window as tkwin, but it must refer to a compatible pixmap or window: one associated with the same screen and with the same depth as tkwin. The x, y, width, and height arguments define the bounding box of the border region within drawable (usually x and y are zero and width and height are the dimensions of the window), and borderWidth specifies the number of pixels actually occupied by the border. The

relief argument indicates which of several three-dimensional effects is

desired: TKRELIEFRAISED means that the interior of the rectangle should appear raised relative to the exterior of the rectangle, and TKRELIEFSUNKEN means that the interior should appear depressed. TKRELIEFGROOVE and TKRELIEFRIDGE mean that there should appear to be a groove or ridge around the exterior of the rectangle. TTkkFFiillll33DDRReeccttaannggllee is somewhat like TTkkDDrraaww33DDRReeccttaannggllee except that it

first fills the rectangular area with the background color (one corre-

sponding to the color used to create border). Then it calls TTkkDDrraaww33DDRReeccttaannggllee to draw a border just inside the outer edge of the rectangular area. The argument relief indicates the desired effect (TKRELIEFFLAT means no border should be drawn; all that happens is to fill the rectangle with the background color). The procedure TTkkDDrraaww33DDPPoollyyggoonn may be used to draw more complex shapes

with a three-dimensional appearance. The pointPtr and numPoints argu-

ments define a trajectory, polyBorderWidth indicates how wide the bor-

der should be (and on which side of the trajectory to draw it), and leftRelief indicates which side of the trajectory should appear raised. TTkkDDrraaww33DDPPoollyyggoonn draws a border around the given trajectory using the

colors from border 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. TTkkFFiillll33DDPPoollyyggoonn is to TTkkDDrraaww33DDPPoollyyggoonn what TTkkFFiillll33DDRReeccttaannggllee is to TTkkDDrraaww33DDRReeccttaannggllee: it fills the polygonal area with the background color from border, then calls TTkkDDrraaww33DDPPoollyyggoonn to draw a border around the area (unless leftRelief is TKRELIEFFLAT; in this case no border is drawn). The procedures TTkk33DDVVeerrttiiccaallBBeevveell and TTkk33DDHHoorriizzoonnttaallBBeevveell provide

lower-level drawing primitives that are used by procedures such as

TTkkDDrraaww33DDRReeccttaannggllee. These procedures are also useful in their own right for drawing rectilinear border shapes. TTkk33DDVVeerrttiiccaallBBeevveell draws a vertical beveled edge, such as the left or right side of a rectangle, and TTkk33DDHHoorriizzoonnttaallBBeevveell draws a horizontal beveled edge, such as the top or bottom of a rectangle. Each procedure takes x, y, width, and height arguments that describe the rectangular area of the beveled edge

(e.g., width is the border width for TTkk33DDVVeerrttiiccaallBBeevveell). The leftBor-

der and topBorder arguments indicate the position of the border rela-

tive to the ``inside'' of the object, and relief indicates the relief

of the inside of the object relative to the outside. TTkk33DDVVeerrttiiccaall-

BBeevveell just draws a rectangular region. TTkk33DDHHoorriizzoonnttaallBBeevveell draws a trapezoidal region to generate mitered corners; it should be called after TTkk33DDVVeerrttiiccaallBBeevveell (otherwise TTkk33DDVVeerrttiiccaallBBeevveell will overwrite the mitering in the corner). The leftIn and rightIn arguments to TTkk33DDHHoorriizzoonnttaallBBeevveell 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 leftIn and

rightIn, and the bottom bevel should be drawn with 0 for both argu-

ments. The procedure TTkkSSeettBBaacckkggrroouunnddFFrroommBBoorrddeerr will modify the background

pixel and/or pixmap of tkwin to produce a result compatible with bor-

der. For color displays, the resulting background will just be the color specified when border was created; for monochrome displays, the

resulting background will be a light stipple pattern, in order to dis-

tinguish the background from the illuminated portion of the border. Given a token for a border, the procedure TTkkNNaammeeOOff33DDBBoorrddeerr will return the color name that was used to create the border. The procedure TTkk33DDBBoorrddeerrCCoolloorr returns the XColor structure that will be used for flat surfaces drawn for its border argument by procedures like TTkkFFiillll33DDRReeccttaannggllee. The return value corresponds to the color

name that was used to create the border. The XColor, and its associ-

ated pixel value, will remain allocated as long as border exists. The procedure TTkk33DDBBoorrddeerrGGCC returns one of the X graphics contexts that are used to draw the border. The argument which selects which one of the three possible GC's: TK3DFLATGC returns the context used for flat surfaces, TK3DLIGHTGC returns the context for light shadows, and TK3DDARKGC returns the context for dark shadows. When a border is no longer needed, TTkkFFrreeee33DDBBoorrddeerrFFrroommOObbjj or | TTkkFFrreeee33DDBBoorrddeerr should be called to release the resources associated | with it. For TTkkFFrreeee33DDBBoorrddeerrFFrroommOObbjj the border to release is specified | with the window and color name used to create the border; for | TTkkFFrreeee33DDBBoorrddeerr the border to release is specified with the Tk3DBorder | token for the border. There should be exactly one call to | TTkkFFrreeee33DDBBoorrddeerrFFrroommOObbjj or TTkkFFrreeee33DDBBoorrddeerr for each call to | TTkkAAlllloocc33DDBBoorrddeerrFFrroommOObbjj or TTkkGGeett33DDBBoorrddeerr. KKEEYYWWOORRDDSS

3D, background, border, color, depressed, illumination, object, poly-

gon, raised, shadow, three-dimensional effect

Tk 8.1 TkAlloc3DBorderFromObj(3)