API Reference

class EventQueue(handler, widget=None, maxsize=0)

This is a subclass of the standard library queue.Queue.

An EventQueue feeds any objects sent to it into a handler function that is called from the main Tk event loop.

NOTE:

The constructor for EventQueue must be called from the main Tk thread.

handler

A callable that will be called to handle a process. It is called as handler(event) where event is a value that has previously been put() to the EventQueue. The handler is called from the tkinter event loop and may interact with tkinter objects, however note that it is not passed the widget that was passed to the EventQueue constructor.

widget

A tkinter widget, or None to use the default root widget. This widget reference is used to create a Tk event handler; it doesn’t really have to be associated with the events that are to be generated or handled.

maxsize

The maximum size of the queue. If maxsize <= 0 the size is not limited.

TODO: talk about exceptions from handler, and how to feed events in.

An EventQueue implements the context manager protocol, which means it can be used like this:

with EventQueue(handler=handle_event) as q:
    invoke_process_to_feed_events_to(q)

The context manager exit operation calls drain() on the queue, so all events have been processed by the time the with completes.

put(event, block=True, timeout=None)

Add an event to the queue.

block

If True (the default), then wait if the queue is full, otherwise raise queue.Full immediately.

timeout

If block is True, specifies the maximum time to wait, in seconds, before raising :exc:queue.Full if the queue remains full. A value of None means wait indefinitely. Ignored if block is False.

put_nowait(event)

Add an event to the queue without waiting.

Either puts the event, or raises queue.Full immediately.

drain()

Close the queue for further events, and process any that are waiting.

class EventGenerator(*, generator=None, handler=None, start=True, queue=None, widget=None, group=None, name=None, maxsize=0)

An EventGenerator is a subclass of threading.Thread.

The constructor creates and optionally starts a thread that fetches values from an iterable, and feeds each into a EventQueue which in turn will make callbacks to a handler function, to process the events in the main Tk thread.

generator

An iterable that will provide the events to be processed.

It will be called from a new thread, and each value that it generates will be put into a queue.

queue

The queue into which to put the generated events.

If None is passed, a new EventQueue is created, using the handler, widget and maxsize parameters - see EventQueue for descriptions of those.

start

A boolean that indicates whether the thread should be started.

The default is to start the thread immediately. This saves having to write an explicit call to start().

group

Should be None.

This is reserved for a future extension to threading.Thread.

name

A name for the thread.

If None is passed, a name of the form EventGenerator-N is used, where N is an integer.

Most of the above parameters will rarely be needed. The most typical pattern is expected to be:

EventGenerator(
    generator=source_of_events,
    handler=handler_of_events,
    widget=my_toplevel_widget
)

This creates a (notionally) unlimited sized EventQueue which handles events put into it by calling handler_of_events from an event handler associated with my_toplevel_widget. The events are generated by a thread that calls source_of_events until it is exhausted.

EventGenerator implements the context manager protocol. If used as a context manager, exiting the context implies calling drain() and so exit is delayed until the generator is exhausted and the queue drained - i.e. until all events have been processed.

start()

Starts the event collection thread (a loop that calls the generator specified in the constructor).

This call is unnecessary if start=True was passed (or defaulted) to the constructor.

join(timeout=None)

Waits (for up to timeout seconds, or indefinitely if timeout is None) for completion of the event generator. Note: does not drain the queue.

drain(timeout=None)

Wait until the generator and queue have been processed.

Calls join(timeout) and then calls drain on the queue (even if the join timed out).

run()

Consumes the generator iterable and sends each value to the queue.

Terminates when and if the generator terminates.

You might want to override this in a subclass if you want to use generators that have unusual ways of signalling (early?) completion.