Tk_CanvasPs(3tk)

💖 Tk_CanvasPs — the Postscript Glow-Up Station 💖

okay bestie, so this is a page from the Tk Library Procedures manual, and it's all about the little helper functions that canvas type managers use to make Postscript. It's giving backstage-pass energy — you don't call these directly, the canvas internals do. 🎀

---

✨ NAME ✨

Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple — utility procedures for generating Postscript for canvases 🦋

---

✨ SYNOPSIS ✨

#include <tk.h>

double
Tk_CanvasPsY(canvas, canvasY)

int
Tk_CanvasPsBitmap(interp, canvas, bitmap, x, y, width, height)

int
Tk_CanvasPsColor(interp, canvas, colorPtr)

int
Tk_CanvasPsFont(interp, canvas, tkFont)

Tk_CanvasPsPath(interp, canvas, coordPtr, numPoints)

int
Tk_CanvasPsStipple(interp, canvas, bitmap)

---

✨ ARGUMENTS ✨

• Tk_Canvas canvas (in) — a token that identifies a canvas widget for which Postscript is being generated. it's the main character of this whole operation 👑
• double canvasY (in) — a Y-coordinate, but in canvas-space, not Postscript-space. we'll get to why that matters, hold on 🙈
• Tcl_Interp *interp (in/out) — a Tcl interpreter. Postscript gets appended to its result, or the result might get replaced with an error message instead. so it's both the notepad and the complaint box 💅
• Pixmap bitmap (in) — the bitmap to use for generating Postscript.
• int x (in) — X-coordinate within the bitmap of the left edge of the region you wanna output.
• int y (in) — Y-coordinate within the bitmap of the top edge of the region you wanna output.
• int width (in) — width of the region of the bitmap to output, in pixels.
• int height (in) — height of the region of the bitmap to output, in pixels.
• XColor *colorPtr (in) — info about the color value to set in the Postscript.
• Tk_Font tkFont (in) — the font you want Postscript generated for.
• double *coordPtr (in) — pointer to an array of coordinates for one or more points, given in canvas coordinates. the order in coordPtr is x1, y1, x2, y2, x3, y3, and so on. so it's pairs, always pairs, no solo flops here 🫶
• Tcl_Size numPoints (in) — how many points live at coordPtr.

---

✨ DESCRIPTION ✨

So these procedures get called by canvas type managers to handle the common little tasks involved in generating Postscript. Most of them take a canvas argument, which refers to a canvas widget that Postscript is being generated for. it's a whole collaborative vibe. 💜

Tk_CanvasPsY takes a y-coordinate in the space of a canvas, and returns the value that should be used for that point in the Postscript currently being generated for canvas. like, why the remix? because Postscript puts its origin at the lower-left corner, whereas X puts its origin at the upper-left corner. so Y needs the transformation, and X... doesn't. canvas x coordinates can be used directly in Postscript with zero transformation. no cap. ✨

Tk_CanvasPsBitmap generates Postscript describing a region of a bitmap. it comes out in proper image data format for Postscript, meaning data between angle brackets, one bit per pixel. the Postscript gets appended to the result of interpreter interp, and TCL_OK is returned — unless something goes wrong, in which case TCL_ERROR is returned and the interpreter result gets overwritten with an error message. 💀

Tk_CanvasPsColor generates Postscript that sets the current color to match its colorPtr argument, and it takes into account any color map specified in the postscript command. same deal: appended to interp's result, TCL_OK on success, and on error TCL_ERROR plus the interpreter's result gets overwritten with an error message. 🎨

Tk_CanvasPsFont generates Postscript that sets the current font to match tkFont as closely as possible. it takes into account any font map specified in the postscript command, and it does the best it can at mapping X fonts to Postscript fonts. honestly? it's trying its best and we respect that. it appends the Postscript to interpreter interp's result and returns TCL_OK unless an error occurs, in which case TCL_ERROR is returned and the interpreter's result gets overwritten with an error message. 🔤

Tk_CanvasPsPath generates Postscript that sets the current path to the set of points given by coordPtr and numPoints. it appends the resulting Postscript to the result of interpreter interp. that's it, that's the whole thing, and it ate. 🛤️

Tk_CanvasPsStipple generates Postscript that fills the current path in stippled fashion. it uses bitmap as the stipple pattern and the current Postscript color. the rule is: ones in the stipple bitmap get drawn in the current color, and zeroes are not drawn at all. the Postscript is appended to interpreter interp's result and TCL_OK is returned, unless an error occurs — in which case TCL_ERROR is returned and the interpreter's result gets overwritten with an error message. 🍓

lowkey important: every one of these "append and return TCL_OK" situations has the same drama clause — error means TCL_ERROR and your interpreter result is gone, replaced by the error message. protect your result bestie 😭

---

✨ KEYWORDS ✨

bitmap, canvas, color, font, path, Postscript, stipple

---

and that's the whole page, no crumbs left 💅 this one's from Tk 4.0, and the page itself is Tk_CanvasPs(3tk) — so go forth and generate Postscript, you've absolutely got this, periodt 🌈✨