bindtags(3pm)

💖 bindtags(3pm) — bestie edition ✨

okay so this is Tk::bindtags, from the User Contributed Perl Documentation section of the manual, and it's literally about figuring out which bindings apply to a window and in what order they get evaluated. iykyk 💅

---

✨ NAME ✨

Tk::bindtags — determine which bindings apply to a window, and the order of evaluation 🦋

---

🌸 SYNOPSIS 🌸

$widget->bindtags([tagList]);

@tags = $widget->bindtags;

---

👑 DESCRIPTION 👑

So when you make a binding with the bind command, it gets attached to <em>something</em>. That something could be:

• a specific window, like $widget
• a class name, like Tk::Button
• the magic keyword all
• or honestly just... any other string you want

All of these are what we call binding tags. periodt.

Every window has a whole list of binding tags, and that list is what decides how events get processed for that window. When an event happens in a window, it gets applied to each of the window's tags in order — and for each tag, the most specific binding that matches both the tag and the event is the one that runs. Want the full tea on how that matching process works? Go read Tk::bind. 🫶

By default, every window has four binding tags, and they are:

1. the window's class name
2. the name of the window
3. the name of the window's nearest toplevel ancestor
4. all

...in that exact order. ✨

Toplevel windows only get three tags by default, because for a toplevel, the toplevel name is the same as the window's own name. no dupe needed 💀

⚠️ okay important heads up bestie: this order is different from the order Tcl/Tk uses. Tcl/Tk puts the window <em>ahead</em> of the class name in the binding order. why? because Tcl is procedural, not object oriented, so the normal way Tcl/Tk apps override class bindings is with an <em>instance</em> binding. but with perl/Tk, the normal way to override a class binding is to <em>derive a class</em>. the perl/Tk order makes instance bindings run <em>after</em> the class binding, which means instance bind callbacks can actually make use of state changes (like changes to the selection, for example) that the class bindings already made. slay. 🔥

The bindtags command is your girl for reading <em>and</em> modifying a window's binding tags. 💅

• If you call $widget->bindtags with <strong>no argument</strong>, you get the current set of binding tags for $widget back as a list. 🎀
• If you <em>do</em> pass the <em>tagList</em> argument, it has to be a <strong>reference to an array</strong> — and the tags for $widget get changed to the elements of that array. (you can make a reference to an anonymous array by wrapping the elements in [ ], iconic behavior honestly)

The elements of <em>tagList</em> can be arbitrary strings or widget objects. and here's the thing — if no window exists for an object at the time an event gets processed, then that tag is just <em>ignored</em> for that event. 🙈

The order of the elements in <em>tagList</em> is what determines the order in which binding callbacks get executed in response to events. for example:

 $b->bindtags([$b,ref($b),$b->toplevel,'all'])

that applies the Tcl/Tk binding order, which means binding callbacks get evaluated for a button (say) $b so that:

1. $b's instance bindings get invoked first
2. followed by bindings for $b's class
3. followed by bindings for $b's toplevel
4. followed by all bindings

and if <em>tagList</em> is an <strong>empty list</strong>, i.e. [], then the binding tags for $widget get returned to the perl/Tk default state described up above. reset button, we love her 🌈

You can also use the bindtags command to introduce arbitrary <em>additional</em> binding tags for a window, or to <em>remove</em> standard tags. for example:

 $b->bindtags(['TrickyButton',$b->toplevel,'all'])

that replaces the (say) Tk::Button tag for $b with TrickyButton. which means the default widget bindings for buttons — the ones associated with the Tk::Button tag — will no longer apply to $b, but any bindings associated with TrickyButton (maybe some new button behavior you cooked up 🍓) <em>will</em> apply. main character energy honestly.

---

💀 BUGS 💀

ngl, the current mapping of the 'native' Tk behaviour of this method is <em>counter intuitive</em> — like, it returns a list but only accepts a reference to an array?? make it make sense. 😭

The perl/Tk interface may get tidied up at some point. returning a list is sensible, so most likely the fix will be to allow a list to be passed in to set the bindtags. we'll see bestie. 🤷♀️

---

🦋 SEE ALSO 🦋

Tk::bind Tk::callbacks

---

⭐ KEYWORDS ⭐

binding, event, tag

---

okay that's the whole page, you ate that 💅 this was perl v5.40.1, dated 2025-04-13, and it's filed under bindtags(3pm). go forth and bind responsibly bestie 🎀✨🫶