Tcl_DoOneEvent(3)

💖 Tcl_DoOneEvent — bestie, the event loop is CALLING ✨

okay so this is Tcl_DoOneEvent(3) from the Tcl Library Procedures, and no cap, she is the moment 👑

---

🌸 NAME 🌸

Tcl_DoOneEvent — sit around waiting for events, then run the handlers for them 💅

---

🎀 SYNOPSIS 🎀

#include <tcl.h>

int
Tcl_DoOneEvent(flags)

---

🦋 ARGUMENTS 🦋

• int flags (in) — bestie this is normally just zero, like, no thoughts head empty. But you can pass 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. Mix and match, she's flexible 💁♀️

---

✨ DESCRIPTION ✨

This procedure is the entry point to Tcl's event loop, like the front door of the whole party 🚪🎉. She's the one responsible for waiting for events and dispatching the event handlers that got created with procedures such as Tk_CreateEventHandler, Tcl_CreateFileHandler, Tcl_CreateTimerHandler, and Tcl_DoWhenIdle.

Here's the run of show, in order, no skips:

1. Tcl_DoOneEvent peeks to see if events are already sitting on the Tcl event queue. If yes? She calls the handler(s) for the first (oldest) event, removes it from the queue, and returns. periodt ✂️
2. If there are no events ready to be handled, she checks for new events from all possible sources. If she finds any, she 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, she checks for Tcl_DoWhenIdle callbacks. If any are found, she invokes all of them and returns 👯♀️
4. Finally, if no events or idle callbacks turned up, Tcl_DoOneEvent sleeps until an event occurs. Then she adds any new events to the Tcl event queue, calls handlers for the first event, and returns 😴➡️🔥

The normal return value is 1, which signifies that some event was processed (scroll down for the other alternatives, bestie).

If the flags argument is non-zero, it restricts the kinds of events that Tcl_DoOneEvent will process. Flags may 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. This is equivalent to OR-ing together all of the above flags, or just specifying none of them at all. Same energy, different outfit 💃
• TCL_DONT_WAIT — do NOT sleep. Process only the events that are ready at the time of the call 🏃♀️

If any of the flags TCL_WINDOW_EVENTS, TCL_FILE_EVENTS, TCL_TIMER_EVENTS, or TCL_IDLE_EVENTS is set, then the only events 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 👀

The TCL_DONT_WAIT flag makes Tcl_DoOneEvent not put the process to sleep: she'll check for events, but if none are found she returns immediately with a return value of 0 to indicate that no work was done 💀

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. She is not about to stand there waiting on nothing, bestie 🚫⏳

Tcl_DoOneEvent may be invoked recursively. For example, it is possible to invoke Tcl_DoOneEvent recursively from a handler that was called by Tcl_DoOneEvent. This sort of operation is useful in some modal situations — like 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. main character energy, honestly 🫶

---

👑 KEYWORDS 👑

callback, event, handler, idle, timer

---

and that's the whole page, babe 💜 this one's straight outta the Tcl 7.5 era, dated 7.5, and it lives in the Tcl_DoOneEvent(3) section of the Tcl library manual — go forth and dispatch your events, you absolute icon 🌈✨