---
name: "DoOneEvent"
section: "3tk"
platform: "linux"
package: "tk40-dev"
version: "4.0p3-5"
release: "Debian 1.3 (Bo)"
platforms: ["linux"]
url: "https://new.carta.tech/DoOneEvent/3tk"
---

# DoOneEvent(3tk)

wait for events and invoke event handlers

```

```

## NAME

Tk\_DoOneEvent, Tk\_MainLoop, Tk\_HandleEvent - wait for events and invoke event handlers

## SYNOPSIS

```
#include <tk.h>

int
Tk_DoOneEvent(flags)

Tk_MainLoop()

Tk_HandleEvent(eventPtr)
```

## ARGUMENTS

- int *flags* (in)

  This parameter is normally zero.  It may be an OR-ed combination of any of the following flag bits:  TK\_X\_EVENTS, TK\_FILE\_EVENTS, TK\_TIMER\_EVENTS, TK\_IDLE\_EVENTS, TK\_ALL\_EVENTS, or TK\_DONT\_WAIT.

- XEvent *\*eventPtr* (in)

  Pointer to X event to dispatch to relevant handler(s).

  ```

  ```

## DESCRIPTION

These three procedures are responsible for waiting for events and dispatching to event handlers created with the procedures **Tk\_CreateEventHandler**, **Tk\_CreateFileHandler**, **Tk\_CreateTimerHandler**, and **Tk\_DoWhenIdle**. **Tk\_DoOneEvent** is the key procedure.  It waits for a single event of any sort to occur, invokes the handler(s) for that event, and then returns.  **Tk\_DoOneEvent** first checks for X events and file-related events;  if one is found then it calls the handler(s) for the event and returns.  If there are no X or file events pending, then **Tk\_DoOneEvent** checks to see if timer callbacks are ready;  if so, it makes a single callback and returns.  If no timer callbacks are ready, **Tk\_DoOneEvent** checks for **Tk\_DoWhenIdle** callbacks;  if any are found, it invokes all of them and returns. Finally, if no events or work have been found, **Tk\_DoOneEvent** sleeps until a timer, file, or X event occurs;  then it processes the first event found (in the order given above) and returns. The normal return value is 1 to signify that some event or callback was processed. If no event or callback is processed (under various conditions described below), then 0 is returned.

If the *flags* argument to **Tk\_DoOneEvent** is non-zero then it restricts the kinds of events that will be processed by **Tk\_DoOneEvent**. *Flags* may be an OR-ed combination of any of the following bits:

- **TK\_X\_EVENTS** -

  Process X events.

- **TK\_FILE\_EVENTS** -

  Process file events.

- **TK\_TIMER\_EVENTS** -

  Process timer events.

- **TK\_IDLE\_EVENTS** -

  Process **Tk\_DoWhenIdle** callbacks.

- **TK\_ALL\_EVENTS** -

  Process all kinds of events:  equivalent to OR-ing together all of the above flags or specifying none of them.

- **TK\_DONT\_WAIT** -

  Don't sleep:  process only events that are ready at the time of the call.

If any of the flags **TK\_X\_EVENTS**, **TK\_FILE\_EVENTS**, **TK\_TIMER\_EVENTS**, or **TK\_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 **TK\_ALL\_EVENTS**, which causes all event types to be processed.

The **TK\_DONT\_WAIT** flag causes **Tk\_DoWhenIdle** 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. **Tk\_DoOneEvent** will also return 0 without doing anything if *flags* is **TK\_IDLE\_EVENTS** and there are no **Tk\_DoWhenIdle** callbacks pending. Lastly, **Tk\_DoOneEvent** will return 0 without doing anything if there are no events or work found and if there are no files, displays, or timer handlers to wait for.

**Tk\_MainLoop** is a procedure that loops repeatedly calling **Tk\_DoOneEvent**.  It returns only when there are no applications left in this process (i.e. no main windows exist anymore).  Most X applications will call **Tk\_MainLoop** after initialization;  the main execution of the application will consist entirely of callbacks invoked by **Tk\_DoOneEvent**.

**Tk\_HandleEvent** is a lower-level procedure invoked by **Tk\_DoOneEvent**.  It makes callbacks to any event handlers (created by calls to **Tk\_CreateEventHandler**) that match *eventPtr* and then returns.  In some cases it may be useful for an application to read events directly from X and dispatch them by calling **Tk\_HandleEvent**, without going through the additional mechanism provided by **Tk\_DoOneEvent**.

These procedures may be invoked recursively.  For example, it is possible to invoke **Tk\_DoOneEvent** recursively from a handler called by **Tk\_DoOneEvent**.  This sort of operation is useful in some modal situations, such as when a notifier has been popped up and an application wishes to wait for the user to click a button in the notifier before doing anything else.

## KEYWORDS

callback, event, handler, idle, timer