canvas::sqmap(n)

💅 canvas::sqmap 💅

okay bestie, welcome to canvas::sqmap — straight out of the Variations on a canvas manual page (that's the manual name, we're folding it in right here at the top ✨). It's a canvas widget with a map background made of square tiles, and it is genuinely iconic. Let's get into it.

---

✨ 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 gives you an extended canvas widget for showing maps built out of a set of square image tiles. The tiles are literally the background of the canvas, and every other canvas item you add is always drawn in front of them — main character energy for your regular items, lowkey background duty for the tiles. 👑

The number of tiles shown, the tile size, and where the images come from are all configurable. Fully yours to control, no cap.

---

🎀 API 🎀

💖 ::canvas::sqmap pathName ?options? 💖

Creates the canvas pathName and configures it. The new widget supports all of the options and methods of a regular canvas, plus the options and methods described below. Best of both worlds, fr fr.

The result of the command is pathName.

---

💜 OPTIONS 💜

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

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

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

This option may be left undefined — yes, the canvas can operate totally fine 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, bestie). All the other grid cells will just be empty. 🫥

• -viewport-command — specifies a command prefix to invoke when the viewport of the canvas is changed, so you can keep track of where in the scroll-region you're at, at all times. Think: driving derivative displays, or keeping items in view by moving them as the viewport moves. Very useful, very slay. 🎀
• -image-on-load — the 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 given by -grid-cell-command. A lil placeholder moment. ⏳
• -image-on-unset — the value is an image. If you specify it, that image is shown in a cell for which the callback given by -grid-cell-command reported that there's no actual image to show. The "sorry babe, nothing here" picture. 🙈

---

🌸 METHODS 🌸

⭐ canvasName image set cell image

Invoking this places the image into the specified cell of the background. The cell is given as a 2-element list containing the row and column number, in that order.

Note that an image is allowed to be associated with and displayed in multiple cells of the canvas. Sharing is caring. 💖

⭐ canvasName image unset cell

Invoking this declares the specified cell of the background as empty — an existing image shown by that cell will be forgotten. The cell is given as a 2-element list containing the row and column number, in that order.

⭐ canvasName flush

Invoking this forces the canvas to completely reload the images for all cells. 😭

⚠️ Do not use this method if the canvas is running without a -grid-cell-command, because in that case the canvas will simply forget all its images without being able to reload them. Like, gone gone. Be careful bestie.

---

👑 IMAGE OWNERSHIP 👑

Heads up: the canvas does not take ownership of the images it shows in the background. So when we say the canvas "forgets" an image, that means only that the association between a grid cell and the shown image is broken. The image itself is not deleted. 🚫🗑️

Managing the lifecycle of those images is your responsibility — the user of the canvas. You're the main character here, you handle it. 💅

---

💀 BUGS, IDEAS, FEEDBACK 💀

This document — and the package it describes — will undoubtedly contain bugs and other problems (ngl, that's just how software is 😭). Please report such things in the category canvas of the Tklib Trackers [http://core.tcl.tk/tklib/reportlist].

Please also report any ideas for enhancements you have for either the package and/or the documentation — we love ideas actually. 🫶

---

🔥 KEYWORDS 🔥

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

---

and that's the whole page, bestie — brought to you by tklib, version 0.3.1, on the canvas::sqmap(n) page. go build a map, you've got this 💜🦋✨