Constants

Note

These constants may be used, but using the string values themselves in your program is equally supported. These constants are used internally by urwid just to avoid possible misspelling, but the example programs and tutorials tend to use the string values.

Widget Sizing Methods

One or more of these values returned by Widget.sizing() to indicate supported sizing methods.

urwid.FLOW = 'flow'

Widget that is given a number of columns by its parent widget and calculates the number of rows it requires for rendering e.g. Text

urwid.BOX = 'box'

Widget that is given a number of columns and rows by its parent widget and must render that size e.g. ListBox

urwid.FIXED = 'fixed'

Widget that knows the number of columns and rows it requires and will only render at that exact size e.g. BigText

Horizontal Alignment

Used to horizontally align text in Text widgets and child widgets of Padding and Overlay.

urwid.LEFT = 'left'

urwid.CENTER = 'center'

urwid.RIGHT = 'right'

Veritcal Alignment

Used to vertically align child widgets of Filler and Overlay.

urwid.TOP = 'top'

urwid.MIDDLE = 'middle'

urwid.BOTTOM = 'bottom'

Width and Height Settings

Used to distribute or set widths and heights of child widgets of Padding, Filler, Columns, Pile and Overlay.

urwid.PACK = 'pack'

Ask the child widget to calculate the number of columns or rows it needs

urwid.GIVEN = 'given'

A set number of columns or rows, e.g. (‘given’, 10) will have exactly 10 columns or rows given to the child widget

urwid.RELATIVE = 'relative'

A percentage of the total space, e.g. (‘relative’, 50) will give half of the total columns or rows to the child widget

urwid.RELATIVE_100 = ('relative', 100)

urwid.WEIGHT = 'weight'

A weight value for distributing columns or rows, e.g. (‘weight’, 3) will give 3 times as many columns or rows as another widget in the same container with (‘weight’, 1).

Text Wrapping Modes

urwid.SPACE = 'space'

wrap text on space characters or at the boundaries of wide characters

urwid.ANY = 'any'

wrap before any wide or narrow character that would exceed the available screen columns

urwid.CLIP = 'clip'

clip before any wide or narrow character that would exceed the available screen columns and don’t display the remaining text on the line

urwid.ELLIPSIS = 'ellipsis'

clip if text would exceed the available screen columns, add an ellipsis character at the end

Validation

Used by the validator of an Edit to report what is wrong with its text, and by Notifications to colour a message.

class urwid.Severity(*values)

How serious a ValidationMessage or a message of Notifications is.

The members are ordered, so max() gives the worst of several.

class urwid.ValidationMessage(severity: Severity, message: str)

One finding of a validator about a whole value, such as the text of an Edit.

Create new instance of ValidationMessage(severity, message)

message: str

Alias for field number 1

severity: Severity

Alias for field number 0

Mouse buttons

The button of a mouse event, see Mouse Input.

class urwid.MouseButton(*values)

The button of a mouse event, as Widget.mouse_event() receives it.

The values are the numbers the screens pass as plain int, and a member compares equal to them. A number above FORWARD has no name. MouseButton(n) returns a member named BUTTON_<n> for it instead of raising, since a terminal may report buttons urwid does not name. Mouse Input lists which buttons each screen delivers and when a release does not name its button.

>>> MouseButton.LEFT == 1
True
>>> MouseButton(10).name
'BUTTON_10'

BACK = 8

FORWARD = 9

LEFT = 1

MIDDLE = 2

RIGHT = 3

UNKNOWN = 0

WHEEL_DOWN = 5

WHEEL_LEFT = 6

WHEEL_RIGHT = 7

WHEEL_UP = 4

Foreground and Background Colors

Standard background and foreground colors

urwid.BLACK = 'black'

urwid.DARK_RED = 'dark red'

urwid.DARK_GREEN = 'dark green'

urwid.BROWN = 'brown'

urwid.DARK_BLUE = 'dark blue'

urwid.DARK_MAGENTA = 'dark magenta'

urwid.DARK_CYAN = 'dark cyan'

urwid.LIGHT_GRAY = 'light gray'

Standard foreground colors (not safe to use as background)

urwid.DARK_GRAY = 'dark gray'

urwid.LIGHT_RED = 'light red'

urwid.LIGHT_GREEN = 'light green'

urwid.YELLOW = 'yellow'

urwid.LIGHT_BLUE = 'light blue'

urwid.LIGHT_MAGENTA = 'light magenta'

urwid.LIGHT_CYAN = 'light cyan'

urwid.WHITE = 'white'

User’s terminal configuration default foreground or background

Note

There is no way to tell if the user’s terminal has a light or dark color as their default foreground or background, so it is highly recommended to use this setting for both foreground and background when you do use it.

urwid.DEFAULT = 'default'

Color of the enclosing display attribute

urwid.INHERIT = 'inherit'

Take the foreground or background color from the enclosing display attribute, see Inherited Foreground and Background.

256 and 88 Color Foregrounds and Backgrounds

Constants are not defined for these colors.

See also

24-Bit Foreground and Background Colors

Signal Names

urwid.UPDATE_PALETTE_ENTRY = 'update palette entry'

sent by BaseScreen (and subclasses like display.raw.Screen) when a palette entry is changed. MainLoop does not handle it. display.raw.Screen subscribes to it itself, so that its next draw_screen() redraws every row.

An entry that BaseScreen.register_palette() removes with replace=True is sent with the specifications it is drawn with from then on: the terminal’s default colors.

display.common.INPUT_DESCRIPTORS_CHANGED = 'input descriptors changed'

sent by BaseScreen (and subclasses like display.raw.Screen) when the list of input file descriptors has changed. MainLoop handles this signal by updating the file descriptors being watched by its event loop.

Command Names

Command names are used as values in CommandMap instances. Widgets look up the command associated with keypresses in their Widget.keypress() methods.

You may define any new command names as you wish and look for them in your own widget code. These are the standard ones expected by code included in Urwid.

urwid.REDRAW_SCREEN = 'redraw screen'

Default associated keypress: ‘ctrl l’

MainLoop.process_input() looks for this command to force a screen refresh. This is useful in case the screen becomes corrupted.

urwid.ACTIVATE = 'activate'

Default associated keypresses: ‘ ‘ (space), ‘enter’

Activate a widget such as a Button, CheckBox or RadioButton.

urwid.CURSOR_UP = 'cursor up'

Default associated keypress: ‘up’

Move the cursor or selection up one row.

urwid.CURSOR_DOWN = 'cursor down'

Default associated keypress: ‘down’

Move the cursor or selection down one row.

urwid.CURSOR_LEFT = 'cursor left'

Default associated keypress: ‘left’

Move the cursor or selection left one column.

urwid.CURSOR_RIGHT = 'cursor right'

Default associated keypress: ‘right’

Move the cursor or selection right one column.

urwid.CURSOR_PAGE_UP = 'cursor page up'

Default associated keypress: ‘page up’

Move the cursor or selection up one page.

urwid.CURSOR_PAGE_DOWN = 'cursor page down'

Default associated keypress: ‘page down’

Move the cursor or selection down one page.

urwid.CURSOR_MAX_LEFT = 'cursor max left'

Default associated keypress: ‘home’

Move the cursor or selection to the leftmost column.

urwid.CURSOR_MAX_RIGHT = 'cursor max right'

Default associated keypress: ‘end’

Move the cursor or selection to the rightmost column.