uevent(n)

💖 uevent — User events 💖

okay bestie, sit down, we're learning uevent(n) from the Tcllib manual, and honestly? it's giving event-system royalty. 👑

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require uevent ?0.3.2?

package require logger

::uevent::bind tag event command

command tag event details

::uevent::unbind token

::uevent::generate tag event ?details?

::uevent::list

::uevent::list tag

::uevent::list tag event

::uevent::watch::tag::add pattern command

{*}command bound tag

{*}command unbound tag

::uevent::watch::tag::remove token

::uevent::watch::event::add tag_pattern event_pattern command

{*}command bound tag event

{*}command unbound tag event

::uevent::watch::event::remove token

---

🌸 DESCRIPTION 🌸

So this package is literally a whole general-purpose facility for handling user events. It lets you bind arbitrary commands to arbitrary events on arbitrary tags, remove those bindings, and generate events. The full trio, no notes. 💅

The main character difference between this and the event system baked into the Tcl/Tk core? The core one can only generate virtual events, and only for widgets. You literally cannot use the builtin stuff to bind to events on arbitrary (pseudo-)objects, and it can't generate events for those either. Not it. 🙅♀️

Here we can, because we just assume every object in question is represented by its own tag. Which works out, because we allow arbitrary tags. iconic behavior tbh. 🦋

More differences, bestie, because the list is not done:

1. This package uses only a two-level hierarchy — tags and events — to handle everything. Meanwhile the Tcl/Tk system uses three levels: objects, tags, and events, with a n:m relationship between objects and tags. Different eras, honestly.
2. This package triggers all bound commands for a tag/event combination, and they are independent of each other. A bound command cannot force the event processing core to abort the processing of the commands coming after it. No queue-jumping, no sabotage. periodt.

---

👑 API 👑

The package exports eight commands, all specified below. Also, important: when the package is used from within Tcl 8.5+, all the higher commands are ensembles — meaning the :: separators can be replaced by spaces. slay.

💫 ::uevent::bind tag event command

Using this command registers the command prefix to be triggered when the event occurs for the tag. The result is an opaque token representing the binding. And heads up: if the same combination of <tag,event,command> is used multiple times, the same token is returned by every call. Same token, same energy. 🫶

The signature of the command prefix is:

command tag event details

where details contains the argument(s) of the event. Its contents are event specific and have to be agreed upon between the actual event generator and the consumer. This package just transfers the information and does not perform any processing beyond that. It's the messenger, not the message. 💌

💫 ::uevent::unbind token

This one releases the event binding represented by the token. The token has to be the result of a call to ::uevent::bind. The result of the command is the empty string. bye bye binding 👋

💫 ::uevent::generate tag event ?details?

Generates an event for the tag, triggering all commands bound to that combination. The details argument is simply passed unchanged to all event handlers. It is the responsibility of the code generating and consuming the event to have an agreement about the format and contents of the information carried in there. The result of the command is the empty string.

⚠️ Note that all bound commands are triggered, independently of each other. The event handlers cannot assume a specific order. They are also not called synchronously with the invocation of this command — they're simply put into the event queue for processing when the system returns to the event loop. Patience, bestie. 🧘♀️

Generating an event for an unknown tag, or for a <tag,event> combination which has no commands bound to it, is allowed — such calls will just be ignored. no drama, no error, just vibes. ✨

💫 ::uevent::list

In this form the command returns a list containing the names of all tags which have events with commands bound to them. the whole roster 📋

💫 ::uevent::list tag

In this format the command returns a list containing the names of all events for the tag which have commands bound to them. Specifying an unknown tag — i.e. a tag without event and commands — will cause the command to throw an error. 💀

💫 ::uevent::list tag event

In this format the command returns a list containing all commands bound to the event for the tag. Specifying an unknown tag or unknown event will cause the command to throw an error. 🚨

💫 ::uevent::watch::tag::add pattern command

This command sets up a sort of reverse events. Events are generated — i.e. the command prefix is invoked — when observers bind to and unbind from specific tags. observers are being observed, very meta, very main character energy. 👁️

⚠️ Note that the command prefix is only invoked twice per tag: first when the first command is bound to any event of the tag, and second when the last command bound to the tag is removed.

The signature of the command prefix is:

{*}command bound tag

{*}command unbound tag

The result of the command is a token representing the watcher. 🎀

💫 ::uevent::watch::tag::remove token

Removes a watcher for (un)bind events on tags.

The result of the command is the empty string.

💫 ::uevent::watch::event::add tag_pattern event_pattern command

Sets up a sort of reverse events too. Events generated — i.e. the command prefix invoked — when observers bind to and unbind from specific combinations of tags and events. we love a specific combo 🍓

⚠️ Note that the command prefix is only invoked twice per tag/event combination: first when the first command is bound to it, and second when the last command bound to it is removed.

The signature of the command prefix is:

{*}command bound tag event

{*}command unbound tag event

The result of the command is a token representing the watcher. 🌈

💫 ::uevent::watch::event::remove token

Removes a watcher for (un)bind events on tag/event combinations.

The result of the command is the empty string.

---

😭 BUGS, IDEAS, FEEDBACK 😭

Okay real talk. This document, and the package it describes, will undoubtedly contain bugs and other problems. Not a read, just a fact of life. 🫠

Please report such in the category uevent of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either the package and/or the documentation. We want the ideas!! give them to us!!

When proposing code changes, please provide unified diffs, i.e. the output of diff -u. 📝

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. iykyk 💅

---

🦋 SEE ALSO 🦋

• hook(n)

---

⭐ KEYWORDS ⭐

bind, event, generate event, hook, unbind

---

🎀 CATEGORY 🎀

Programming tools

---

💜 COPYRIGHT 💜

Copyright (c) 2007-2012 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

okay that's the whole page bestie, you ate it, you're literally a Tcl event system expert now. 🌟

this came to you from tcllib, version 0.3.2, and the page is uevent(n). mwah, go bind some events. 💖✨🎀