Display Modules

class urwid.BaseScreen

Base class for Screen classes (raw_display.Screen, .. etc)

register_palette(palette)

Register a set of palette entries.

palette – a list of (name, like_other_name) or (name, foreground, background, mono, foreground_high, background_high) tuples

The (name, like_other_name) format will copy the settings from the palette entry like_other_name, which must appear before this tuple in the list.

The mono and foreground/background_high values are optional ie. the second tuple format may have 3, 4 or 6 values. See register_palette_entry() for a description of the tuple values.

register_palette_entry(name, foreground, background, mono=None, foreground_high=None, background_high=None)

Register a single palette entry.

name – new entry/attribute name

foreground – a string containing a comma-separated foreground color and settings

Color values: ‘default’ (use the terminal’s default foreground), ‘black’, ‘dark red’, ‘dark green’, ‘brown’, ‘dark blue’, ‘dark magenta’, ‘dark cyan’, ‘light gray’, ‘dark gray’, ‘light red’, ‘light green’, ‘yellow’, ‘light blue’, ‘light magenta’, ‘light cyan’, ‘white’

Settings: ‘bold’, ‘underline’, ‘blink’, ‘standout’

Some terminals use ‘bold’ for bright colors. Most terminals ignore the ‘blink’ setting. If the color is not given then ‘default’ will be assumed.

background – a string containing the background color

Background color values: ‘default’ (use the terminal’s default background), ‘black’, ‘dark red’, ‘dark green’, ‘brown’, ‘dark blue’, ‘dark magenta’, ‘dark cyan’, ‘light gray’

mono – a comma-separated string containing monochrome terminal settings (see “Settings” above.)

None = no terminal settings (same as ‘default’)

foreground_high – a string containing a comma-separated foreground color and settings, standard foreground colors (see “Color values” above) or high-colors may be used

High-color example values: ‘#009’ (0% red, 0% green, 60% red, like HTML colors) ‘#fcc’ (100% red, 80% green, 80% blue) ‘g40’ (40% gray, decimal), ‘g#cc’ (80% gray, hex), ‘#000’, ‘g0’, ‘g#00’ (black), ‘#fff’, ‘g100’, ‘g#ff’ (white) ‘h8’ (color number 8), ‘h255’ (color number 255)

None = use foreground parameter value

background_high – a string containing the background color, standard background colors (see “Background colors” above) or high-colors (see “High-color example values” above) may be used

None = use background parameter value
run_wrapper(fn, *args, **kwargs)

Start the screen, call a function, then stop the screen. Extra arguments are passed to start.

Deprecated in favor of calling start as a context manager.

start(*args, **kwargs)

Set up the screen. If the screen has already been started, does nothing.

May be used as a context manager, in which case stop() will automatically be called at the end of the block:

with screen.start():
...

You shouldn’t override this method in a subclass; instead, override _start().

raw_display

class urwid.raw_display.Screen(input=<open file '<stdin>', mode 'r' at 0x7fddf9a4d150>, output=<open file '<stdout>', mode 'w' at 0x7fddf9a4d1e0>)

Initialize a screen that directly prints escape codes to an output terminal.

clear()

Force the screen to be completely repainted on the next call to draw_screen().

draw_screen((maxcol, maxrow), r)

Paint screen with rendered canvas.

flush()

Flush the output buffer.

You may wish to override this if you’re using something other than regular files for input and output.

get_available_raw_input()

Return any currently-available input. Does not block.

This method is only used by the default hook_event_loop implementation; you can safely ignore it if you implement your own.

get_cols_rows()

Return the terminal dimensions (num columns, num rows).

get_input(raw_keys=False)

Return pending input as a list.

raw_keys – return raw keycodes as well as translated versions

This function will immediately return all the input since the last time it was called. If there is no input pending it will wait before returning an empty list. The wait time may be configured with the set_input_timeouts function.

If raw_keys is False (default) this function will return a list of keys pressed. If raw_keys is True this function will return a ( keys pressed, raw keycodes ) tuple instead.

Examples of keys returned:

  • ASCII printable characters: ” ”, “a”, “0”, “A”, “-”, “/”
  • ASCII control characters: “tab”, “enter”
  • Escape sequences: “up”, “page up”, “home”, “insert”, “f1”
  • Key combinations: “shift f1”, “meta a”, “ctrl b”
  • Window events: “window resize”

When a narrow encoding is not enabled:

  • “Extended ASCII” characters: “xa1”, “xb2”, “xfe”

When a wide encoding is enabled:

  • Double-byte characters: “xa1xea”, “xb2xd4”

When utf8 encoding is enabled:

  • Unicode characters: u”u00a5”, u’u253c”

Examples of mouse events returned:

  • Mouse button press: (‘mouse press’, 1, 15, 13),

    (‘meta mouse press’, 2, 17, 23)

  • Mouse drag: (‘mouse drag’, 1, 16, 13),

    (‘mouse drag’, 1, 17, 13), (‘ctrl mouse drag’, 1, 18, 13)

  • Mouse button release: (‘mouse release’, 0, 18, 13),

    (‘ctrl mouse release’, 0, 17, 23)

get_input_descriptors()

Return a list of integer file descriptors that should be polled in external event loops to check for user input.

Use this method if you are implementing your own event loop.

hook_event_loop(event_loop, callback)

Register the given callback with the event loop, to be called with new input whenever it’s available. The callback should be passed a list of processed keys and a list of unprocessed keycodes.

Subclasses may wish to use parse_input to wrap the callback.

modify_terminal_palette(entries)

entries - list of (index, red, green, blue) tuples.

Attempt to set part of the terminal palette (this does not work on all terminals.) The changes are sent as a single escape sequence so they should all take effect at the same time.

0 <= index < 256 (some terminals will only have 16 or 88 colors) 0 <= red, green, blue < 256

parse_input(event_loop, callback, codes, wait_for_more=True)

Read any available input from get_available_raw_input, parses it into keys, and calls the given callback.

The current implementation tries to avoid any assumptions about what the screen or event loop look like; it only deals with parsing keycodes and setting a timeout when an incomplete one is detected.

codes should be a sequence of keycodes, i.e. bytes. A bytearray is appropriate, but beware of using bytes, which only iterates as integers on Python 3.

reset_default_terminal_palette()

Attempt to set the terminal palette to default values as taken from xterm. Uses number of colors from current set_terminal_properties() screen setting.

set_input_timeouts(max_wait=None, complete_wait=0.125, resize_wait=0.125)

Set the get_input timeout values. All values are in floating point numbers of seconds.

max_wait – amount of time in seconds to wait for input when
there is no input pending, wait forever if None
complete_wait – amount of time in seconds to wait when
get_input detects an incomplete escape sequence at the end of the available input
resize_wait – amount of time in seconds to wait for more input
after receiving two screen resize requests in a row to stop Urwid from consuming 100% cpu during a gradual window resize operation
set_mouse_tracking(enable=True)

Enable (or disable) mouse tracking.

After calling this function get_input will include mouse click events along with keystrokes.

set_terminal_properties(colors=None, bright_is_bold=None, has_underline=None)
colors – number of colors terminal supports (1, 16, 88 or 256)
or None to leave unchanged
bright_is_bold – set to True if this terminal uses the bold
setting to create bright colors (numbers 8-15), set to False if this Terminal can create bright colors without bold or None to leave unchanged
has_underline – set to True if this terminal can use the
underline setting, False if it cannot or None to leave unchanged
signal_init()

Called in the startup of run wrapper to set the SIGWINCH and SIGCONT signal handlers.

Override this function to call from main thread in threaded applications.

signal_restore()

Called in the finally block of run wrapper to restore the SIGWINCH and SIGCONT signal handlers.

Override this function to call from main thread in threaded applications.

unhook_event_loop(event_loop)

Remove any hooks added by hook_event_loop.

write(data)

Write some data to the terminal.

You may wish to override this if you’re using something other than regular files for input and output.

curses_display

class urwid.curses_display.Screen
clear()

Force the screen to be completely repainted on the next call to draw_screen().

draw_screen((cols, rows), r)

Paint screen with rendered canvas.

get_cols_rows()

Return the terminal dimensions (num columns, num rows).

get_input(raw_keys=False)

Return pending input as a list.

raw_keys – return raw keycodes as well as translated versions

This function will immediately return all the input since the last time it was called. If there is no input pending it will wait before returning an empty list. The wait time may be configured with the set_input_timeouts function.

If raw_keys is False (default) this function will return a list of keys pressed. If raw_keys is True this function will return a ( keys pressed, raw keycodes ) tuple instead.

Examples of keys returned:

  • ASCII printable characters: ” ”, “a”, “0”, “A”, “-”, “/”
  • ASCII control characters: “tab”, “enter”
  • Escape sequences: “up”, “page up”, “home”, “insert”, “f1”
  • Key combinations: “shift f1”, “meta a”, “ctrl b”
  • Window events: “window resize”

When a narrow encoding is not enabled:

  • “Extended ASCII” characters: “xa1”, “xb2”, “xfe”

When a wide encoding is enabled:

  • Double-byte characters: “xa1xea”, “xb2xd4”

When utf8 encoding is enabled:

  • Unicode characters: u”u00a5”, u’u253c”

Examples of mouse events returned:

  • Mouse button press: (‘mouse press’, 1, 15, 13),

    (‘meta mouse press’, 2, 17, 23)

  • Mouse button release: (‘mouse release’, 0, 18, 13),

    (‘ctrl mouse release’, 0, 17, 23)

set_input_timeouts(max_wait=None, complete_wait=0.1, resize_wait=0.1)

Set the get_input timeout values. All values have a granularity of 0.1s, ie. any value between 0.15 and 0.05 will be treated as 0.1 and any value less than 0.05 will be treated as 0. The maximum timeout value for this module is 25.5 seconds.

max_wait – amount of time in seconds to wait for input when
there is no input pending, wait forever if None
complete_wait – amount of time in seconds to wait when
get_input detects an incomplete escape sequence at the end of the available input
resize_wait – amount of time in seconds to wait for more input
after receiving two screen resize requests in a row to stop urwid from consuming 100% cpu during a gradual window resize operation
set_mouse_tracking(enable=True)

Enable mouse tracking.

After calling this function get_input will include mouse click events along with keystrokes.

web_display

class urwid.web_display.Screen
clear()

Force the screen to be completely repainted on the next call to draw_screen().

(does nothing for web_display)

draw_screen((cols, rows), r)

Send a screen update to the client.

get_cols_rows()

Return the screen size.

get_input(raw_keys=False)

Return pending input as a list.

register_palette(l)

Register a list of palette entries.

l – list of (name, foreground, background) or
(name, same_as_other_name) palette entries.

calls self.register_palette_entry for each item in l

register_palette_entry(name, foreground, background, mono=None)

Register a single palette entry.

name – new entry/attribute name foreground – foreground colour background – background colour mono – monochrome terminal attribute

See curses_display.register_palette_entry for more info.

run_wrapper(fn)

Run the application main loop, calling start() first and stop() on exit.

set_mouse_tracking(enable=True)

Not yet implemented

start()

This function reads the initial screen size, generates a unique id and handles cleanup when fn exits.

web_display.set_preferences(..) must be called before calling this function for the preferences to take effect

stop()

Restore settings and clean up.

tty_signal_keys(*args, **vargs)

Do nothing.

html_fragment

class urwid.html_fragment.HtmlGenerator
clear()

Force the screen to be completely repainted on the next call to draw_screen().

(does nothing for html_fragment)

draw_screen((cols, rows), r)

Create an html fragment from the render object. Append it to HtmlGenerator.fragments list.

get_cols_rows()

Return the next screen size in HtmlGenerator.sizes.

get_input(raw_keys=False)

Return the next list of keypresses in HtmlGenerator.keys.

set_mouse_tracking(enable=True)

Not yet implemented

urwid.html_fragment.screenshot_init(sizes, keys)

Replace curses_display.Screen and raw_display.Screen class with HtmlGenerator.

Call this function before executing an application that uses curses_display.Screen to have that code use HtmlGenerator instead.

sizes – list of ( columns, rows ) tuples to be returned by each call
to HtmlGenerator.get_cols_rows()
keys – list of lists of keys to be returned by each call to
HtmlGenerator.get_input()

Lists of keys may include “window resize” to force the application to call get_cols_rows and read a new screen size.

For example, the following call will prepare an application to:
  1. start in 80x25 with its first call to get_cols_rows()
  2. take a screenshot when it calls draw_screen(..)
  3. simulate 5 “down” keys from get_input()
  4. take a screenshot when it calls draw_screen(..)
  5. simulate keys “a”, “b”, “c” and a “window resize”
  6. resize to 20x10 on its second call to get_cols_rows()
  7. take a screenshot when it calls draw_screen(..)
  8. simulate a “Q” keypress to quit the application
screenshot_init( [ (80,25), (20,10) ],
[ [“down”]*5, [“a”,”b”,”c”,”window resize”], [“Q”] ] )
urwid.html_fragment.screenshot_collect()

Return screenshots as a list of HTML fragments.

lcd_display

class urwid.lcd_display.LCDScreen
class urwid.lcd_display.CFLCDScreen(device_path, baud)

Common methods for Crystal Fontz LCD displays

device_path – eg. ‘/dev/ttyUSB0’ baud – baud rate

class urwid.lcd_display.CF635Screen(device_path, baud=115200, repeat_delay=0.5, repeat_next=0.125, key_map=['up', 'down', 'left', 'right', 'enter', 'esc'])

Crystal Fontz 635 display

20x4 character display + cursor no foreground/background colors or settings supported

see CGROM for list of close unicode matches to characters available

6 button input up, down, left, right, enter (check mark), exit (cross)

device_path – eg. ‘/dev/ttyUSB0’ baud – baud rate repeat_delay – seconds to wait before starting to repeat keys repeat_next – time between each repeated key key_map – the keys to send for this device’s buttons

get_input_descriptors()

return the fd from our serial device so we get called on input and responses

get_input_nonblocking()

Return a (next_input_timeout, keys_pressed, raw_keycodes) tuple.

The protocol for our device requires waiting for acks between each command, so this method responds to those as well as key press and release events.

Key repeat events are simulated here as the device doesn’t send any for us.

raw_keycodes are the bytes of messages we received, which might not seem to have any correspondence to keys_pressed.

program_cgram(index, data)

Program character data. Characters available as chr(0) through chr(7), and repeated as chr(8) through chr(15).

index – 0 to 7 index of character to program

data – list of 8, 6-bit integer values top to bottom with MSB on the left side of the character.

set_backlight(value)

Set backlight brightness

value – 0 to 100

set_cursor_style(style)
style – CURSOR_BLINKING_BLOCK, CURSOR_UNDERSCORE,
CURSOR_BLINKING_BLOCK_UNDERSCORE or CURSOR_INVERTING_BLINKING_BLOCK
set_lcd_contrast(value)

value – 0 to 255

set_led_pin(led, rg, value)

led – 0 to 3 rg – 0 for red, 1 for green value – 0 to 100

class urwid.lcd_display.KeyRepeatSimulator(repeat_delay, repeat_next)

Provide simulated repeat key events when given press and release events.

If two or more keys are pressed disable repeating until all keys are released.

repeat_delay – seconds to wait before starting to repeat keys repeat_next – time between each repeated key

next_event()

Return (remaining, key) where remaining is the number of seconds (float) until the key repeat event should be sent, or None if no events are pending.

sent_event()

Cakk this method when you have sent a key repeat event so the timer will be reset for the next event

Table of contents

Previous topic

Widget Classes

Next topic

List Walker Classes

This Page