# Display Modules

class urwid.BaseScreen

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

  clear() → None

    Clear the screen if possible.

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

  get_cols_rows() → tuple[int, int]

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

    Default (fallback) is 80x24.

  register_palette(palette: Iterable[tuple[str, str] | tuple[str, str, str] | tuple[str, str, str, str] | tuple[str, str, str, str, str, str]]) → None

    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: str | None, foreground: str, background: str, mono: str | None = None, foreground_high: str | None = None, background_high: str | None = None) → 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’, ‘strikethrough’

    > 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) → None

    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) → StoppingContext

    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.display.raw.Screen(input: ~typing.TextIO = <_io.TextIOWrapper name='<stdin>' mode='r' encoding='utf-8'>, output: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, bracketed_paste_mode=False, focus_reporting=False)

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

  bracketed_paste_mode – enable bracketed paste mode in the host terminal.

    If the host terminal supports it, the application will receive begin paste and end paste keystrokes when the user pastes text.

  focus_reporting – enable focus reporting in the host terminal.

    If the host terminal supports it, the application will receive focus in and focus out keystrokes when the application gains and loses focus.

  get_cols_rows() → tuple[int, int]

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

  get_input_descriptors() → list[socket.socket | IO | int]

    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.

    This method is only called by hook_event_loop, so if you override that, you can safely ignore this.

  hook_event_loop(event_loop: EventLoop, callback: Callable[[list[str], list[int]], Any]) → None

    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.

  signal_init() → None

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

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

  signal_restore() → None

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

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

  unhook_event_loop(event_loop: EventLoop) → None

    Remove any hooks added by hook_event_loop.

## Curses display

class urwid.display.curses.Screen
  clear() → None

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

  draw_screen(size: tuple[int, int], canvas: Canvas) → None

    Paint screen with rendered canvas.

  get_cols_rows() → tuple[int, int]

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

  get_input(raw_keys: Literal[False]) → list[str]
  get_input(raw_keys: Literal[True]) → tuple[list[str], list[int]]

    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: float | None = None, complete_wait: float = 0.1, resize_wait: float = 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: bool = True) → None

    Enable mouse tracking.

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

## WEB display

class urwid.display.web.Screen
  clear() → None

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

    (does nothing for web_display)

  draw_screen(size: tuple[int, int], canvas: Canvas) → None

    Send a screen update to the client.

  get_cols_rows() → tuple[int, int]

    Return the screen size.

  get_input(raw_keys: Literal[False]) → list[str]
  get_input(raw_keys: Literal[True]) → tuple[list[str], list[int]]

    Return pending input as a list.

  register_palette(palette) → None

    Register a list of palette entries.

    palette – 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: str | None, foreground: str, background: str, mono: str | None = None, foreground_high: str | None = None, background_high: str | None = None) → 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.

  set_mouse_tracking(enable: bool = True) → None

    Not yet implemented

  start() → StoppingContext

    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() → None

    Restore settings and clean up.

  tty_signal_keys(*args, **vargs)

    Do nothing.

## HTML fragment

class urwid.display.html_fragment.HtmlGenerator
  draw_screen(size: tuple[int, int], canvas: Canvas) → None

    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: Literal[False]) → list[str]
  get_input(raw_keys: Literal[True]) → tuple[list[str], list[int]]

    Return the next list of keypresses in HtmlGenerator.keys.

urwid.display.html_fragment.screenshot_init(sizes: list[tuple[int, int]], keys: list[list[str]]) → None

  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.display.html_fragment.screenshot_collect() → list[str]

  Return screenshots as a list of HTML fragments.

## LCD display

class urwid.display.lcd.LCDScreen

  Base class for LCD-based screens.

  get_cols_rows()

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

    Default (fallback) is 80x24.

class urwid.display.lcd.CFLCDScreen(device_path: str, baud: int)

  Common methods for Crystal Fonts LCD displays

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

  exception InvalidPacket
  exception MoreDataRequired

class urwid.display.lcd.CF635Screen(device_path: str, baud: int = 115200, repeat_delay: float = 0.5, repeat_next: float = 0.125, key_map: Iterable[str] = ('up', 'down', 'left', 'right', 'enter', 'esc'))

  Crystal Fontz 635 display

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

  see CGROM for a 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() → list[int]

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

  get_input_nonblocking() → tuple[None, list[str], list[int]]

    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: int, data: Sequence[int]) → None

    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: int) → None

    Set backlight brightness

    value – 0 to 100

  set_cursor_style(style: Literal[1, 2, 3, 4]) → None
    style – CURSOR_BLINKING_BLOCK, CURSOR_UNDERSCORE,

      CURSOR_BLINKING_BLOCK_UNDERSCORE or CURSOR_INVERTING_BLINKING_BLOCK

  set_lcd_contrast(value: int) → None

    value – 0 to 255

  set_led_pin(led: Literal[0, 1, 2, 3], rg: Literal[0, 1], value: int) → None

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

class urwid.display.lcd.KeyRepeatSimulator(repeat_delay: float, repeat_next: float)

  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() → tuple[float, str] | None

    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() → None

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