canvas::highlight(n)

💅 canvas::highlight(n) — Variations on a canvas

okay so bestie, this is the manual page for canvas::highlight, from the Variations on a canvas chapter of the docs, and it's genuinely so useful — it's all about managing the highlighting of canvas items, or whole item groups (you know, the ones a tag points at). let's get into it 🎀

---

✨ SYNOPSIS ✨

package require Tcl  8.5

package require Tk  8.5

package require canvas::highlight  ?0.1?

::canvas::highlight on canvas tagOrId cmd

::canvas::highlight off canvas tagOrId

{*}cmd on canvas item

{*}cmd off canvas clientdata

like, yes, that's a lot of lines, but they're all important, trust 🫶

---

🌸 DESCRIPTION 🌸

this package hands you utility commands for setting up and tearing down highlights for canvas items or item groups — and the groups are identified by a tag, iykyk. that's the whole vibe. ✨

---

👑 API 👑

💖 ::canvas::highlight on canvas tagOrId cmd

this one sets up a general highlight. fr fr here's the breakdown:

• the items of the canvas canvas that should get highlighted this way are identified by tagOrId
• the cmd prefix is the thing that provides the implementation — like, the how to actually perform the highlight part

the signature of that command prefix? it's described later, down in the Highlight callback section, so don't stress 💅

the result of this command is the empty string. yep. that's it. that's the result. 😌

Limitations (and she is serious about these, ngl):

1. when a highlight is active, no other highlight can be activated. so nested highlights are literally not possible. periodt.
2. the system may break if a highlight is removed from within its own highlight callback. 💀 don't do that.

🦋 ::canvas::highlight off canvas tagOrId

this one removes any highlight set on the items of canvas canvas identified by tagOrId. clean, simple, iconic.

the result of the command is the empty string. again. consistency queen. ✨

---

🧚 HIGHLIGHT CALLBACK 🧚

so the highlight callback is a command prefix, and it gets invoked in two ways. both are main character energy, just in different situations:

⭐ {*}cmd on canvas item

this form shows up when the mouse has entered (one of) the item(s) the highlight was set up for. so now the callback has to do whatever reconfiguration is necessary to highlight that item (group). go off 💅

some details you can't skip:

• the result of the command can be anything. the system stores it as client information and passes it unchanged to the un-highlight callback for its use. so in this manner, the highlight callback is able to maintain custom state all the way from highlighting to un-highlighting. cute, right? 🎀
• note that the callback does not have to maintain state, and it also does not have to actually reconfigure the item (group). in that latter case the callback simply serves as an easy enter/leave notification. lowkey elegant.

💜 {*}cmd off canvas clientdata

this form shows up when the mouse has left (one of) the item(s) of the currently active highlight. now the callback has to do whatever reconfiguration is necessary to un-highlight the item (group).

here's the catch, bestie:

the result of the command must be a boolean value — with the usual values to be true. by returning false instead, the callback can veto the removal of the highlight. yes, really. it has veto power. 👑

---

😭 BUGS, IDEAS, FEEDBACK 😭

this document, and the package it describes, will undoubtedly contain bugs and other problems — no cap, they said it themselves. please report such things in the category canvas of the Tklib Trackers at http://core.tcl.tk/tklib/reportlist.

and please also report any ideas for enhancements you may have for either the package and/or the documentation! they want your thoughts, fr fr 🫶

---

🔥 KEYWORDS 🔥

canvas, enter callback, highlighting, leave callback

---

and that's the whole page! 🌈 this was canvas::highlight(n) — tklib version 0.1, dated back in the day, straight from the Variations on a canvas crew. slay, go highlight something, and remember: no nested highlights. never nested highlights. 💅✨🎀