Tk_Alloc3DBorderFromObj(3tk)

💖 Tk_Alloc3DBorderFromObj 💖 — Tk Library Procedures 🎀

okay bestie, gather round, because this is the manual page for Tk_Alloc3DBorderFromObj(3tk) and it is lowkey iconic. this is part 1, so we're doing the names, the synopsis and the arguments. no sign-off, no goodbye, we're just getting started fr fr ✨

---

✨ NAME ✨

bestie, this is a whole squad of procedures that all hang out together, and their collective mission is: draw borders with three-dimensional appearance. 💅

Here's everyone in the group chat:

• Tk_Alloc3DBorderFromObj
• Tk_ClipDrawableToRect
• Tk_DrawHighlightBorder
• Tk_Get3DBorder
• Tk_Get3DBorderColors
• 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

---

🌸 SYNOPSIS 🌸

#include <tk.h>

Tk_3DBorder
Tk_Alloc3DBorderFromObj(interp, tkwin, objPtr)

Tk_ClipDrawableToRect(display, drawable, x, y, width, height)

Tk_DrawHighlightBorder(tkwin, fgGC, bgGC, highlightWidth, drawable)

Tk_3DBorder
Tk_Get3DBorder(interp, tkwin, colorName)

Tk_Get3DBorderColors(border, bgColorPtr, darkColorPtr, lightColorPtr)

Tk_3DBorder
Tk_Get3DBorderFromObj(tkwin, objPtr)

Tk_Draw3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)

Tk_Fill3DRectangle(tkwin, drawable, border, x, y, width, height, borderWidth, relief)

Tk_Draw3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)

Tk_Fill3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)

Tk_3DVerticalBevel(tkwin, drawable, border, x, y, width, height, leftBevel, relief)

Tk_3DHorizontalBevel(tkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief)

Tk_SetBackgroundFromBorder(tkwin, border)

const char *
Tk_NameOf3DBorder(border)

XColor *
Tk_3DBorderColor(border)

GC *
Tk_3DBorderGC(tkwin, border, which)

Tk_Free3DBorderFromObj(tkwin, objPtr)

Tk_Free3DBorder(border)

---

💜 ARGUMENTS 💜

every single one of these, no skips, we're being thorough girlies 🫶

• Tcl_Interp *interp (in) — the interpreter you're gonna use to report errors, that's its whole job.
• Tk_Window tkwin (in) — token for the window. heads up tho: for all procedures except Tk_Get3DBorder, this has to be the window that the border was allocated for. no substituting, she's picky.
• Tcl_Obj *objPtr (in) — pointer to a value whose value describes the color that matches the background (aka the flat areas). the illuminated edges will be brighter than this, and the shadowed edges will be darker than this. it's giving contour palette 💄
• const char *colorName (in) — literally the same as objPtr, except the value shows up as a string instead of a value. same energy, different delivery.
• Drawable drawable (in) — the X token for a window or a pixmap; it says where the graphics are gonna be drawn. it must either be the X window for tkwin, or a pixmap with the same screen and depth as tkwin. no mixing and matching bestie.
• Tk_3DBorder border (in) — token for a border that was already allocated earlier, back when you called Tk_Get3DBorder.
• int x (in) — the X-coordinate of the upper-left corner of the rectangle describing the border or bevel, in pixels. 📍
• int y (in) — the Y-coordinate of that same upper-left corner, in pixels.
• int width (in) — width of the rectangle describing the border or bevel, in pixels.
• int height (in) — height of the rectangle describing the border or bevel, in pixels.
• int borderWidth (in) — width of the border in pixels. positive means the border is inside the rectangle given by x, y, width, height; negative means the border is outside the rectangle. inny or outy, you choose.
• int highlightWidth (in) — width of the ring around the outside of the widget, but only if the widget has received the input focus. main character only when she's focused ✨
• int relief (in) — says the 3-D position of the interior relative to the exterior. it should be TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE (and it may also be TK_RELIEF_FLAT for Tk_Fill3DRectangle).
• XPoint *pointPtr (in) — pointer to an array of points describing the set of vertices in a polygon. the polygon doesn't need to be closed — it'll be closed automatically if it isn't. she closes herself, self-sufficient queen 🔥
• int numPoints (in) — number of points at *pointPtr.
• int polyBorderWidth (in) — width of the border in pixels. if it's positive, the border gets drawn to the left of the trajectory given by pointPtr; if it's negative, the border gets drawn to the right of the trajectory. but if leftRelief is TK_RELIEF_GROOVE or TK_RELIEF_RIDGE, then the border is centered on the trajectory instead. ok so it's giving centered when she feels like it 💅
• int leftRelief (in) — the height of the left side of the polygon's path relative to the right. TK_RELIEF_RAISED means the left side should appear higher, and TK_RELIEF_SUNKEN means the right side should appear higher; TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things. for Tk_Fill3DPolygon, TK_RELIEF_FLAT may also be specified to indicate no difference in height at all.
• int leftBevel (in) — non-zero means this bevel forms the left side of the value; zero means it forms the right side.
• int leftIn (in) — non-zero means the left edge of the horizontal bevel angles in, so the bottom of the edge is farther to the right than the top. zero means the edge angles out, so the bottom is farther to the left than the top.
• int rightIn (in) — non-zero means the right edge of the horizontal bevel angles in, so the bottom of the edge is farther to the left than the top. zero means the edge angles out, so the bottom is farther to the right than the top.
• int topBevel (in) — non-zero means this bevel forms the top side of the value; zero means it forms the bottom side.
• int which (in) — specifies which of the border's graphics contexts you want. it must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC. pick one, bestie 🎀
• XColor *bgColorPtr (out) — pointer to the location where the background color of the given border gets stored.
• XColor *darkColorPtr (out) — pointer to the location where the color for the darker areas of the given border gets stored.
• XColor *lightColorPtr (out) — pointer to the location where the color for the lighter areas of the given border gets stored.
• GC fgGC (in) — foreground X graphics context.
• GC fgGC (in) — background X graphics context.

not me noticing both of the last two say fgGC 😭 i'm not touching it, i'm not fixing it, i am simply relaying the facts as they were given to me. we keep every detail, periodt. 💀

✨ DESCRIPTION ✨

okay bestie so these procedures are literally the whole glow-up crew for drawing window borders that look 3D. like, they make your rectangles pop instead of being flat and sad. 💅

Tk_Alloc3DBorderFromObj is the one that does the actual allocating — it sets up the colors and Pixmaps you need to draw a border in the window given by the tkwin argument. the value of objPtr is a standard Tk color name, and that's what decides your border colors. here's the tea though: the color you name in objPtr is not actually used in the border itself. it's telling us the background color for the window (y'know, the color for flat surfaces). the illuminated parts of the border will look brighter than what objPtr says, and the shadowed parts will look darker. it's giving dimension, fr fr. 🌈

Tk_Alloc3DBorderFromObj hands back a token you can use in later calls to Tk_Draw3DRectangle. if something goes wrong while allocating (say, a bogus color name — not the vibe), it returns NULL and drops an error message as the result of the interpreter interp. if it does succeed, it caches the info about the return value in objPtr, which makes future calls to Tk_Alloc3DBorderFromObj with the same objPtr and tkwin way speedier. icon behavior honestly. ✨

Tk_ClipDrawableToRect clips all drawing into the drawable d to the given rectangle. if width or height are negative, it resets to no clipping. after that, drawing into d is offset and clipped as you specified. lowkey niche: this function is only used when TK_NO_DOUBLE_BUFFERING is specified at compile time. so like, don't come for it otherwise.

Tk_DrawHighlightBorder draws a rectangular ring around the outside of a widget to show it's got the input focus. main character moment 🎀. on the Macintosh, this puts a 1 pixel border in the bgGC color between the widget and the focus ring — except when highlightWidth is 0 or 1, in which case the border is left out entirely. and for proper Mac L&F, use a highlightWidth of 3. noted, bestie.

Tk_Get3DBorder is literally identical to Tk_Alloc3DBorderFromObj except the color is specified with a string instead of a value. downside: that stops Tk_Get3DBorder from caching the return value, so it's less efficient than Tk_Alloc3DBorderFromObj. trade-off city. 😭

Tk_Get3DBorderColors returns the used colors of the given border. cute and simple.

Tk_Get3DBorderFromObj returns the token for an existing border, given the window and color name that were used to create it. important: it does not actually create the border — it must already have been created with a previous call to Tk_Alloc3DBorderFromObj or Tk_Get3DBorder. the return value gets cached in objPtr, which speeds up future calls to Tk_Get3DBorderFromObj with the same objPtr and tkwin.

---

once a border structure exists, Tk_Draw3DRectangle can be invoked to draw it. the tkwin argument says which window the border was allocated for, and drawable says which window or pixmap the border gets drawn into. drawable doesn't have to be the same window as tkwin, but it must refer to a compatible pixmap or window — one associated with the same screen and 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 the border actually takes up. then relief picks which three-dimensional effect you want:

• TK_RELIEF_RAISED — the interior of the rectangle should appear raised relative to the exterior.
• TK_RELIEF_SUNKEN — the interior should appear depressed.
• TK_RELIEF_GROOVE and TK_RELIEF_RIDGE — there should appear to be a groove or ridge around the exterior of the rectangle. 🔥

Tk_Fill3DRectangle is kinda like Tk_Draw3DRectangle, except it first fills the rectangular area with the background color (the one corresponding to the color used to create the border). then it calls Tk_Draw3DRectangle to draw a border just inside the outer edge of that area. the relief argument indicates the desired effect — and heads up, TK_RELIEF_FLAT means no border gets drawn at all; all that happens is the rectangle gets filled with the background color. that's it, that's the whole thing. 🙈

the procedure Tk_Draw3DPolygon can draw more complex shapes with that three-dimensional look. the pointPtr and numPoints arguments define a trajectory, polyBorderWidth says how wide the border should be (and on which side of the trajectory to draw it), and leftRelief says which side of the trajectory should appear raised. Tk_Draw3DPolygon draws a border around the given trajectory using the colors from border to get that 3D appearance. if the trajectory is non-self-intersecting, you get a raised or sunken polygon shape. the trajectory may be self-intersecting, although honestly it's not clear how useful that is. 💀

Tk_Fill3DPolygon is to Tk_Draw3DPolygon what Tk_Fill3DRectangle is to Tk_Draw3DRectangle: it fills the polygonal area with the background color from border, then calls Tk_Draw3DPolygon to draw a border around the area — unless leftRelief is TK_RELIEF_FLAT, in which case no border is drawn.

---

the procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel are the lower-level drawing primitives that procedures like Tk_Draw3DRectangle use. but bestie, they're also useful all on their own for drawing rectilinear border shapes. 🫶

Tk_3DVerticalBevel draws a vertical beveled edge, like the left or right side of a rectangle. Tk_3DHorizontalBevel draws a horizontal beveled edge, like the top or bottom of a rectangle. each one takes x, y, width, and height arguments describing the rectangular area of the beveled edge (e.g. for Tk_3DVerticalBevel, width is the border width). the leftBorder and topBorder arguments indicate the position of the border relative to the “inside” of the value, and relief indicates the relief of the inside of the value relative to the outside.

Tk_3DVerticalBevel just draws a rectangular region. Tk_3DHorizontalBevel draws a trapezoidal region to generate mitered corners — so it should be called after Tk_3DVerticalBevel (otherwise Tk_3DVerticalBevel will overwrite the mitering in the corner, rude). the leftIn and rightIn arguments to Tk_3DHorizontalBevel describe the mitering at the corners: a value of 1 means 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 arguments. math but make it fashion. ✨

the procedure Tk_SetBackgroundFromBorder modifies the background pixel and/or pixmap of tkwin to produce a result compatible with border. for color displays, the resulting background is just the color specified when border was created. for monochrome displays, the resulting background becomes a light stipple pattern, so the background stays distinguishable from the illuminated portion of the border. 🌸

given a token for a border, Tk_NameOf3DBorder returns the color name that was used to create that border.

the procedure Tk_3DBorderColor returns the XColor structure that will be used for flat surfaces drawn for its border argument by procedures like Tk_Fill3DRectangle. the return value corresponds to the color name used to create the border. and good news: the XColor, and its associated pixel value, will stay allocated as long as border exists. 💜

the procedure Tk_3DBorderGC returns one of the X graphics contexts used to draw the border. the which argument picks which one of the three possible GC's:

• TK_3D_FLAT_GC — the context used for flat surfaces.
• TK_3D_LIGHT_GC — the context for light shadows.
• TK_3D_DARK_GC — the context for dark shadows.

---

when a border isn't needed anymore, call Tk_Free3DBorderFromObj or Tk_Free3DBorder to release the resources associated with it. for Tk_Free3DBorderFromObj, the border to release is specified with the window and color name used to create it; for Tk_Free3DBorder, it's specified with the Tk_3DBorder token for the border.

⚠️ okay this part matters, bestie: there should be exactly one call to Tk_Free3DBorderFromObj or Tk_Free3DBorder for each call to Tk_Alloc3DBorderFromObj or Tk_Get3DBorder. one in, one out. no skipping, no double-dipping. 💀

---

🌈 KEYWORDS 🌈

3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect

---

and that's the whole page, babe 🎀 this was Tk_Alloc3DBorderFromObj(3tk) from Tk 8.1 — go forth and make those borders dimensional, you absolute icon 👑💖