Urwid Application Overview

Documentation in devlopment

Setup

An Urwid application first needs to set up a display object. The display object will be created using one of the available Display Modules.

import urwid.raw_display
screen = urwid.raw_display.Screen()

After creating the display object the application should register the display object's palette. The palette maps the attributes used by the widgets to foreground and background colours to be displayed.

# attribute name, foreground, background
screen.register_palette([
    ('body','black','light gray'),
    ('header','white','dark red'),
    ('important','dark blue','light gray')])

See also: register_palette reference

Urwid applications also need to set up some widgets to display. One widget that contains all the others is called the "Topmost Widget". This widget will be used to render the screen contents.

# a really simple topmost widget
view = urwid.Filler(urwid.Text(('header', "Hello World!")))

Once an application is ready to start it passes a "main loop" function to the display object's run_wrapper() function. This function initializes the screen and calls the function passed in. When the "main loop" function exits run_wrapper() will take care of restoring the screen settings.

Main Loop

An Urwid application's main loop involves five steps:

1. Query the size of our display (This is only necessary the first time through the loop and after receiving a 'window resize' event)
2. Render the visible widgets
3. Draw the rendered widgets to the screen
4. Read the user's input
5. Pass the input to the widgets to handle (This may involve multiple function calls)

Some special handling of input may be done in the main loop, such as watching for a key that will cause the application to exit. Most of an Urwid application's code should be triggered by widgets events in order to keep the main loop simple and flexible.

Widget events include built-in events like a Button press or a CheckBox state change, as well as custom events captured by subclassing or wrapping widgets.

See also: Modifying Existing Widgets