Main Loop

The MainLoop class ties together a display module, a set of widgets and an event loop. It handles passing input from the display module to the widgets, rendering the widgets and passing the rendered canvas to the display module to be drawn.

You may filter the user’s input before it is passed to the widgets with your own code by using MainLoop.input_filter(), or have special code to handle input not handled by the widgets by using MainLoop.unhandled_input().

You may set alarms to create timed events using MainLoop.set_alarm_at() or MainLoop.set_alarm_in(). These methods automatically add a call to MainLoop.draw_screen() after calling your callback. MainLoop.remove_alarm() may be used to remove alarms.

When the main loop is running, any code that raises an ExitMainLoop exception will cause the loop to exit cleanly. If any other exception reaches the main loop code, it will shut down the screen to avoid leaving the terminal in an unusual state then re-raise the exception for normal handling.

Using MainLoop is highly recommended, but if it does not fit the needs of your application you may choose to use your own code instead. There are no dependencies on MainLoop in other parts of Urwid.

Widgets Displayed

The topmost widget displayed by MainLoop must be passed as the first parameter to the constructor. If you want to change the topmost widget while running, you can assign a new widget to the MainLoop object’s MainLoop.widget attribute. This is useful for applications that have a number of different modes or views.

The displayed widgets will be handling user input, so it is better to extend the widgets that are displayed with your application-specific input handling so that the application’s behaviour changes when the widgets change. If all your custom input handling is done from MainLoop.unhandled_input(), it will be difficult to extend as your application gets more complicated.

Event Loops

Urwid’s event loop classes handle waiting for things for the MainLoop. The different event loops allow you to integrate with Asyncio, Twisted, Glib, Tornado, ZMQ libraries, or use a simple select-based loop. Event loop classes abstract the particulars of waiting for input and calling functions as a result of timeouts.

You will typically only have a single event loop in your application, even if you have more than one MainLoop running.

You can add your own files to watch to your event loop, with the watch_file() method. Using this interface gives you the special handling of ExitMainLoop and other exceptions when using Glib, Twisted or Tornado callbacks.

SelectEventLoop

This event loop is based on select.select(). This is the default event loop created if none is passed to MainLoop.

# same as urwid.MainLoop(widget, event_loop=urwid.SelectEventLoop())
loop = urwid.MainLoop(widget)

AsyncioEventLoop

This event loop integrates with the asyncio module in Python.

import asyncio
evl = urwid.AsyncioEventLoop(loop=asyncio.get_event_loop())
loop = urwid.MainLoop(widget, event_loop=evl)

Note

In case of multithreading or multiprocessing usage required, do not use executor directly! Use instead method run_in_executor() of AsyncioEventLoop, which forward API of the same method from asyncio Event Loop run_in_executor.

Warning

For input handling, selectors based logic is used. Under Windows OS only SelectorEventLoop is supported.

Note

uvloop event loop is not supported officially.

TwistedEventLoop

This event loop uses Twisted’s reactor. It has been set up to emulate SelectEventLoop’s behaviour and will start the reactor and stop it on an error. This is not the standard way of using Twisted’s reactor, so you may need to modify this behaviour for your application.

loop = urwid.MainLoop(widget, event_loop=urwid.TwistedEventLoop())

Note

In case of threading usage required, please use twisted deferToThread method. It supports callbacks if needed. Executors from concurrent.futures are not supported.

GLibEventLoop

This event loop uses GLib’s event loop. This is useful if you are building an application that depends on DBus events, but don’t want to base your application on Twisted.

loop = urwid.MainLoop(widget, event_loop=urwid.GLibEventLoop())

TornadoEventLoop

This event loop integrates with Tornado.

from tornado.ioloop import IOLoop
evl = urwid.TornadoEventLoop(IOLoop())
loop = urwid.MainLoop(widget, event_loop=evl)

Note

In case of multithreading or multiprocessing usage required, do not use executor directly! Use instead method run_in_executor() of TornadoEventLoop, which forward API of the same method from tornado.ioloop.IOLoop (and internally use asyncio run_in_executor).

ZMQEventLoop

This event loop integrates with 0MQ.

evl = urwid.ZMQEventLoop()
loop = urwid.MainLoop(widget, event_loop=evl)