Tk_Alloc3DBorderFromObj(3)

💅 Tk_Alloc3DBorderFromObj(3) — Tk Library Procedures 💅

okay bestie, welcome to the glow-up zone: this is the Tk Library Procedures page for all the 3-D border functions. No cap, it is a whole ensemble cast, and every single one is about making borders look three-dimensional. Let's get into it 💖

---

🌸 NAME 🌸

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 — draw borders with three-dimensional appearance. periodt.

---

✨ SYNOPSIS ✨

The whole callable cast, exactly as written:

#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 argument, in order, with its exact type and in/out energy:

• Tcl_Interp *interp (in) — the interpreter used for error reporting. if something goes sideways, she's holding the receipts.
• Tk_Window tkwin (in) — token for window. for all procedures except Tk_Get3DBorder, this must be the window for which the border was allocated.
• 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. it's giving highlights and shadows, fr.
• const char *colorName (in) — same as objPtr except the value is supplied as a string rather than a value.
• 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.
• Tk_3DBorder border (in) — token for border previously allocated in call to Tk_Get3DBorder.
• 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. positive means border is inside rectangle given by x, y, width, height; negative means border is outside rectangle.
• int highlightWidth (in) — width of ring around the outside of the widget if the widget has received the input focus.
• int relief (in) — indicates 3-D position of interior of value 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 Tk_Fill3DRectangle). choices, choices 💅
• 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).
• 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 leftRelief is TK_RELIEF_GROOVE or TK_RELIEF_RIDGE then the border is centered on the trajectory.
• 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 Tk_Fill3DPolygon, TK_RELIEF_FLAT may also be specified to indicate no difference in height.
• 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 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 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 is desired. must be TK_3D_FLAT_GC, TK_3D_LIGHT_GC, or TK_3D_DARK_GC.
• XColor *bgColorPtr (out) — pointer to location in which to store the background color of the given border.
• XColor *darkColorPtr (out) — pointer to location in which to store the color for darker areas of the given border.
• XColor *lightColorPtr (out) — pointer to location in which to store the color for lighter areas of the given border.
• GC fgGC (in) — foreground X graphics context.
• GC fgGC (in) — background X graphics context.

✨ DESCRIPTION ✨

okay so these procedures are literally the glow-up squad for window borders — they draw borders that look 3D and gorgeous. 💅

Tk_Alloc3DBorderFromObj allocates all 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 the border colors. Here's the twist though: the color indicated by objPtr is not actually used in the border — it's the background color for the window (like, the color for flat surfaces, bestie). The illuminated parts of the border show up brighter than what objPtr says, and the shadowed parts show up darker. It's giving lit-from-within, no cap. ✨

Tk_Alloc3DBorderFromObj hands you back a token that you can use in later calls to Tk_Draw3DRectangle. If something goes sideways while allocating the border info (like, say, a bogus color name 🙈) then NULL is returned and an error message is left as the result of interpreter interp. If it returns successfully, Tk_Alloc3DBorderFromObj caches the info about the return value in objPtr, which speeds up future calls to Tk_Alloc3DBorderFromObj with the same objPtr and tkwin. Caching is the moment, 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. Any subsequent drawing into d gets offset and clipped as specified. Heads up: this function is only used when TK_NO_DOUBLE_BUFFERING is specified at compile time. 🫶

Tk_DrawHighlightBorder draws a rectangular ring around the outside of a widget to show that it has received the input focus — main character energy, honestly. 👑 On the Macintosh, this puts a 1 pixel border in the bgGC color between the widget and the focus ring, except in the case where highlightWidth is 0 or 1, in which case the border is left out. For proper Mac L&F, use a highlightWidth of 3.

Tk_Get3DBorder is identical to Tk_Alloc3DBorderFromObj except the color is specified with a string instead of a value. Which means — plot twist — this prevents Tk_Get3DBorder from caching the return value, so Tk_Get3DBorder is less efficient than Tk_Alloc3DBorderFromObj. 😭

Tk_Get3DBorderColors returns the used colors of the given border. Slay, that's it, that's the whole thing.

Tk_Get3DBorderFromObj returns the token for an existing border, given the window and color name used to create the border. Important: Tk_Get3DBorderFromObj 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 is cached in objPtr, which speeds up future calls to Tk_Get3DBorderFromObj with the same objPtr and tkwin. 🔥

---

Once a border structure has been created, Tk_Draw3DRectangle may be invoked to draw the border. Let's break down the cast of characters, because there are a lot of them:

• The tkwin argument specifies the window for which the border was allocated.
• drawable specifies a window or pixmap in which the border is to be drawn. It 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. (Compatibility check, bestie. 💀)
• 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.
• borderWidth specifies the number of pixels actually occupied by the border.
• The relief argument indicates which of several three-dimensional effects is desired:
  • TK_RELIEF_RAISED — the interior of the rectangle should appear raised relative to the exterior of the rectangle.
  • TK_RELIEF_SUNKEN — the interior should appear depressed.
  • TK_RELIEF_GROOVE — there should appear to be a groove around the exterior of the rectangle.
  • TK_RELIEF_RIDGE — there should appear to be a ridge around the exterior of the rectangle.

Tk_Fill3DRectangle is somewhat like Tk_Draw3DRectangle except it first fills the rectangular area with the background color (the one corresponding to the color used to create border). Then it calls Tk_Draw3DRectangle to draw a border just inside the outer edge of the rectangular area. The relief argument indicates the desired effect — and note that TK_RELIEF_FLAT means no border should be drawn; all that happens is the rectangle gets filled with the background color. Minimalist icon. 🌸

---

The procedure Tk_Draw3DPolygon may be used to draw more complex shapes with a three-dimensional appearance. The pointPtr and numPoints arguments define a trajectory, polyBorderWidth indicates how wide the border should be (and on which side of the trajectory to draw it), and leftRelief indicates which side of the trajectory should appear raised. Tk_Draw3DPolygon draws a border around the given trajectory using the colors from border to produce that three-dimensional look. 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. 🙈 (like… go off I guess?)

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. Symmetry, we love to see it. 🦋

---

The procedures Tk_3DVerticalBevel and Tk_3DHorizontalBevel provide lower-level drawing primitives that get used by procedures like Tk_Draw3DRectangle. They're also useful in their own right 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 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 Tk_3DVerticalBevel). 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 so it can generate mitered corners — and it should be called after Tk_3DVerticalBevel (otherwise Tk_3DVerticalBevel will overwrite the mitering in the corner, and we'd have beef 💀).

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. iykyk ✨

---

The procedure Tk_SetBackgroundFromBorder will modify the background pixel and/or pixmap of tkwin to produce a result compatible with border.

• 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, so that the background can be distinguished from the illuminated portion of the border. 🌈

---

Given a token for a border, the procedure Tk_NameOf3DBorder will return the color name that was used to create the border. Name reveal! 🎀

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 that was used to create the border. The XColor, and its associated pixel value, will remain allocated as long as border exists. Obsessed with a long-term allocation. 💜

The procedure Tk_3DBorderGC 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:

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

---

When a border is no longer needed, Tk_Free3DBorderFromObj or Tk_Free3DBorder should be called 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 the border.
• For Tk_Free3DBorder, the border to release is specified with the Tk_3DBorder token for the border.

⚠️ Bestie, listen to me: there should be exactly one call to Tk_Free3DBorderFromObj or Tk_Free3DBorder for each call to Tk_Alloc3DBorderFromObj or Tk_Get3DBorder. Clean up after yourself, fr fr. 🧹

🌟 KEYWORDS 🌟

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

---

and that's the whole page, bestie, you ate that 💅✨ this lil masterpiece is from Tk 8.1, dated however long ago, and it's the Tk_Alloc3DBorderFromObj(3) page — go forth and draw some gorgeous 3D borders, mwah 🫶🎀🦋