Tcl_DoOneEvent(3tcl)

✨ Tcl_DoOneEvent ✨ (that's the 3tcl manual page bestie, from the Tcl Library Procedures 💖)

🌸 NAME 🌸

Tcl_DoOneEvent — wait for events and invoke event handlers 🦋

---

🎀 SYNOPSIS 🎀

#include <tcl.h>

int
Tcl_DoOneEvent(flags)

---

💜 ARGUMENTS 💜

• int flags (in) — okay so normally this is just zero, no thoughts head empty 💅. But it can also be an OR-ed combo of any of these flag bits: TCL_WINDOW_EVENTS, TCL_FILE_EVENTS, TCL_TIMER_EVENTS, TCL_IDLE_EVENTS, TCL_ALL_EVENTS, or TCL_DONT_WAIT.

---

🔥 DESCRIPTION 🔥

So Tcl_DoOneEvent is literally the entry point to Tcl's event loop — main character energy fr fr 👑. It's the one responsible for waiting for events and dispatching the event handlers that got created with procedures like Tk_CreateEventHandler, Tcl_CreateFileHandler, Tcl_CreateTimerHandler, and Tcl_DoWhenIdle.

Here's the whole vibe check, step by step:

1. Tcl_DoOneEvent checks whether events are already chilling on the Tcl event queue. If they are — it calls the handler(s) for the first (oldest) event, removes it from the queue, and returns. Slay, done. ✨
2. If there are no events ready to be handled, then Tcl_DoOneEvent checks for new events from all possible sources. If it finds any, it puts all of them on Tcl's event queue, calls handlers for the first event on the queue, and returns. 🦋
3. If no events are found at all, Tcl_DoOneEvent checks for Tcl_DoWhenIdle callbacks. If any are found, it invokes all of them and returns. 💖
4. And finally — if there are no events and no idle callbacks, then Tcl_DoOneEvent literally sleeps until an event occurs. Then it adds any new events to the Tcl event queue, calls handlers for the first event, and returns. 😴

The normal return value is 1, to signify that some event was processed (but lowkey there are other alternatives below, keep reading bestie 👀).

---

🌈 The Flags, One By One 🌈

If the flags argument to Tcl_DoOneEvent is non-zero, it restricts the kinds of events that Tcl_DoOneEvent will process. Flags can be an OR-ed combination of any of these bits:

• TCL_WINDOW_EVENTS — process window system events. 🪟
• TCL_FILE_EVENTS — process file events. 📁
• TCL_TIMER_EVENTS — process timer events. ⏰
• TCL_IDLE_EVENTS — process idle callbacks. 💤
• TCL_ALL_EVENTS — process all kinds of events. It's equivalent to OR-ing together all of the above flags, or specifying none of them. The "no thoughts, all events" option, iconic. 👑
• TCL_DONT_WAIT — do not sleep: process only the events that are ready at the time of the call. No waiting around, we're busy. 💅

---

🧚 How The Filtering Actually Works 🧚

If any of the flags TCL_WINDOW_EVENTS, TCL_FILE_EVENTS, TCL_TIMER_EVENTS, or TCL_IDLE_EVENTS is set, then the only events that will be considered are those for which flags are set. Setting none of these flags is equivalent to the value TCL_ALL_EVENTS, which causes all event types to be processed. And if an application has defined additional event sources with Tcl_CreateEventSource, then additional flag values may also be valid, depending on those event sources. So like, other flags can absolutely exist, it's just up to those sources. 🙈

---

💀 The TCL_DONT_WAIT Situation 💀

The TCL_DONT_WAIT flag causes Tcl_DoOneEvent not to put the process to sleep: it will check for events, but if none are found then it returns immediately with a return value of 0 to indicate that no work was done. Not me getting zero, zero, zero 🫶.

Tcl_DoOneEvent will also return 0 without doing anything if the only alternative is to block forever. This can happen, for example, if flags is TCL_IDLE_EVENTS and there are no Tcl_DoWhenIdle callbacks pending, or if no event handlers or timer handlers exist. Yeah bestie, blocking forever is not the move, so it just bails instead. 😭

---

🎀 Recursion, Because Of Course 🎀

Tcl_DoOneEvent may be invoked recursively. For example, it is possible to invoke Tcl_DoOneEvent recursively from a handler called by Tcl_DoOneEvent. This sort of operation is useful in some modal situations, such as when a notification dialog has been popped up and an application wishes to wait for the user to click a button in the dialog before doing anything else. It's giving "wait for the user to make a choice" energy, and honestly? We respect it. 💅✨

---

💖 KEYWORDS 💖

callback, event, handler, idle, timer

---

And that's the whole page bestie!! 🌈✨ This lil' gem lives in the Tcl manual, version 7.5, dated back in the day — so go forth, loop those events, and remember: no cap, always handle your oldest event first. 🦋💜🎀