canvas::sqmap(3tk)

💖 canvas::sqmap — the manual, but make it slay 💖

okay bestie, so this is the manual page for canvas::sqmap from Tcllib/Tklib land — it lives in the 3tk section of the manual, and honestly? it's giving map widget realness. it's part of the tklib fam, version 0.3.1, and it's about to become your new obsession. buckle up 🎀

---

✨ NAME ✨

canvas::sqmap — a canvas with a map background based on square tiles. yes, that's the whole name. it does exactly what it says on the tin and it does it beautifully. 💅

---

🌈 SYNOPSIS 🌈

package require Tcl 8.4

package require Tk 8.4

package require snit

package require uevent::onidle

package require cache::async

package require canvas::sqmap ?0.3.1?

::canvas::sqmap pathName ?options?

canvasName image set cell image

canvasName image unset cell

canvasName flush

---

🦋 DESCRIPTION 🦋

so this package hands you an extended canvas widget for displaying maps that are built out of a bunch of square image tiles. the tiles are the background of the canvas — like, they're back there chilling — and every other canvas item you add is always shown in front of them. main character items only, no competition. 👑

the number of tiles shown, the tile size, and where the images come from? all configurable. your map, your rules. periodt.

---

👑 API 👑

::canvas::sqmap pathName ?options?

creates the canvas called pathName and configures it. the new widget supports all the options and methods of a regular canvas, plus the extra options and methods described below. it's a canvas but upgraded, iykyk.

the result of the command is pathName.

⭐ OPTIONS ⭐

• -grid-cell-width — value is a non-negative integer. it sets the width of the cells that the background is made up of. 📏
• -grid-cell-height — value is a non-negative integer. it sets the height of the cells the background is made up of. 📐
• -grid-cell-command — value is a command prefix. it gets invoked whenever the canvas needs the image for a specific cell of the background, and it gets two extra arguments: the id of the cell, and a command prefix to invoke when the image is ready, or known to not exist.

the id of the cell is a 2-element list with the row and column number of the cell, in this order. the result command prefix (called "$result" in the example below) has to be invoked with either two or three arguments, i.e.

$result set   $cellid $image ; # image is known and ready
$result unset $cellid        ; # image does not exist

this option can be left undefined, meaning the canvas can totally operate without it. in that case the only images shown in grid cells are the ones you explicitly set with the method image set, see the next section. every other grid cell just stays empty. lowkey minimal, highkey valid. 🙈

• -viewport-command — a command prefix to invoke when the viewport of the canvas is changed, so you can keep track of where in the scroll-region we're at, at all times. use it to drive derivative displays, for example, or to keep items in view by moving them as the viewport moves. multitasking queen energy. 💜
• -image-on-load — value is an image. if you specify it, that image is shown in a cell while the actual image for that cell is still loading through the callback from -grid-cell-command. a lil placeholder moment. ✨
• -image-on-unset — value is an image. if specified, it's shown in a cell for which the callback from -grid-cell-command reported that there is no actual image to be shown. the "sorry nothing here" face. 😭

🎀 METHODS 🎀

• canvasName image set cell image — calling this places image into the specified cell of the background. the cell is a 2-element list with row and column number, in this order.

note that an image is allowed to be associated with and displayed in multiple cells of the canvas. sharing is caring fr fr. 🫶

• canvasName image unset cell — calling this declares the specified cell of the background as empty. an existing image shown by this cell will be forgotten. the cell is a 2-element list with row and column number, in this order.
• canvasName flush — calling this forces the canvas to completely reload the images for all cells.

🚨 do not use this method if the canvas is operated without a -grid-cell-command, because in that case the canvas will simply forget all images without being able to reload them. that's not a vibe. that's data loss. 💀

---

🌸 IMAGE OWNERSHIP 🌸

important bestie: the canvas does not take ownership of the images it shows in the background. so when we say the canvas "forgets" an image, that only means the association between a grid cell and the shown image is broken. the image itself is not deleted. managing the lifecycle of the images shown by the canvas is the responsibility of the user of the canvas. you're the parent here, not the canvas. 🧚

---

💀 BUGS, IDEAS, FEEDBACK 💀

this document, and the package it describes, will undoubtedly contain bugs and other problems (not me being dramatic, it's literally in the manual 😭). please report such in the category canvas of the Tklib Trackers at http://core.tcl.tk/tklib/reportlist. please also report any ideas for enhancements you may have for either the package and/or the documentation. feedback is a love language. 💖

---

⭐ KEYWORDS ⭐

canvas, cell, grid, image, map, square map, tile

---

and that's the whole thing, no cap. this page ships with tklib, version 0.3.1, under the canvas::sqmap(3tk) manual entry. go build something iconic with it. 🌈👑✨