Urwid Manual

Table of Contents

• MainLoop
• DisplayModules
• UserInput
• WidgetLayout
• StandardWidgets
• WidgetMethods
• TextLayout
• TextEncodings
• DisplayAttributes
• TextAttributes
• ListBoxContents
• CanvasCache
• EventLoops

Introduction

Purpose

Urwid is a console user interface library for Python. Urwid offers an alternative to using Python's curses module directly and handles many of the difficult and tedious tasks for you.

Overview

Each Urwid component is loosely coupled and designed to be extended by the user.

DisplayModules are responsible for accepting UserInput and converting escape sequences to lists of keystrokes and mouse events. They also draw the screen contents and convert attributes used in the canvases rendered to the actual colors that appear on screen.

The included widgets are really just examples of what can be done with Urwid. It may be helpful to think of Urwid as a console widget construction set rather than a finished UI library like GTK or Qt. WidgetMethods describes the widget interface and WidgetLayout describes how widgets are nested and arranged on the screen.

Text is the bulk of what will be displayed in any console user interface. Urwid supports a number of TextEncodings and Urwid comes with a configurable TextLayout that handles the most of the common alignment and wrapping modes. If you need more flexibility you can also write your own text layout classes.

Urwid supports a range of common DisplayAttributes, including 256-color foreground and background settings, bold, underline and standount settings for displaying text. Not all of these are supported by all terminals, so Urwid helps you write applications that support different color modes depending on what the user's terminal supports and what they choose to enable.

The ListBox is one of Urwid's most powerful widgets, and you may control of the ListBoxContents by using a built-in list walker class or by writing one yourself. This is very useful for scrolling through lists of any significant length, or with nesting, folding and other similar features.

When a widget renders a canvas to be drawn on screen, a weak reference to it is stored in the CanvasCache. This cache is used any time a widget needs to be rendered again, reducing the amount of work required to update the screen. Since only weak references are used, Urwid's display modules will hold on to a reference to the canvas that they are currently displaying as a way to keep the cache alive and populated with current data.

Urwid's MainLoop simplifies handling of input and updating the screen. It also lets you use one of a number of EventLoops, allowing integration with Twisted's reactor or Glib's event loop if desired.