canvas::highlight(3tk)

✨ NAME ✨

canvas::highlight — it's a little helper from the Variations on a canvas crew, and it handles all the highlighting of canvas items or whole item groups for you 💅 (yes, groups = a tag, we'll get there)

---

🌸 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

---

💖 DESCRIPTION 💖

okay so bestie, this package is literally the glow-up department for your canvas 🎀 It hands you utility commands for setting up highlights and tearing them down again — for individual canvas items, or for whole item groups, and a group is identified by a tag. no cap.

---

👑 API 👑

::canvas::highlight on canvas tagOrId cmd

This one sets up a general highlight ✨ The items of canvas canvas that you want glowing in this manner are picked out by tagOrId, and the cmd prefix is the implementation — like, the how to perform the highlight part.

The signature of that command prefix? It's described further down, in the Highlight callback section. keep scrolling 🫶

The result of the command is the empty string. that's it, that's the whole vibe.

Limitations (read these, fr fr 😭):

1. When a highlight is active no other highlight can be activated. Translation: nested highlights are not possible. periodt.
2. The system may break if a highlight is removed from within its highlight callback. like, don't do that 💀

::canvas::highlight off canvas tagOrId

This one removes any highlight set on the items of canvas canvas identified by tagOrId. bye bestie 👋

The result of the command is the empty string.

---

🦋 HIGHLIGHT CALLBACK 🦋

The highlight callback is a command prefix, and it gets invoked in two different ways:

{*}cmd on canvas item

This form fires when the mouse has entered (one of) the item(s) the highlight was set up for 🐭✨ The callback now has to perform any reconfiguration necessary to highlight the item (group). it's giving main character entrance.

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 yes — the highlight callback can maintain custom state all the way from highlighting to un-highlighting. iconic.

Note that the callback does not have to maintain state, nor does it have to actually reconfigure the item (group). In that case the callback simply serves as easy enter/leave notification. lowkey the chillest option 🌈

{*}cmd off canvas clientdata

This form fires when the mouse has left (one of) the item(s) of the currently active highlight 🌙 The callback now has to perform any reconfiguration necessary to un-highlight the item (group).

The result of the command must be a boolean value, with the usual value being true. By returning false instead, the callback can veto the removal of the highlight. yes bestie, you have veto power 💅👑

---

💀 BUGS, IDEAS, FEEDBACK 💀

This document, and the package it describes, will undoubtedly contain bugs and other problems. 😭 it's not a bug it's a feature... no wait, it's a bug. 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 package and/or documentation — we love a glow-up suggestion 🫶

---

⭐ KEYWORDS ⭐

• canvas
• enter callback
• highlighting
• leave callback

---

and that's the whole page, babe 💜 This lil' doc lives in tklib, version 0.1, dated the very same 0.1, and it's filed as canvas::highlight(3tk) — slay, go highlight something gorgeous 🎀✨🦋