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'>, output=<open file '<stdout>', mode 'w'>)¶ 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:
- start in 80x25 with its first call to get_cols_rows()
- take a screenshot when it calls draw_screen(..)
- simulate 5 “down” keys from get_input()
- take a screenshot when it calls draw_screen(..)
- simulate keys “a”, “b”, “c” and a “window resize”
- resize to 20x10 on its second call to get_cols_rows()
- take a screenshot when it calls draw_screen(..)
- 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
-