Urwid 0.9.8.3 Reference

User interface wrappers

function raw_display.Screen [back to top]

raw_display.Screen [back to top]

__init__(self)

clear(self)

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

draw_screen(self, (maxcol, maxrow), r)

Paint screen with rendered canvas.

get_cols_rows(self)

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

get_input(self, 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:  "\xa1\xea", "\xb2\xd4"
 
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(self)

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 yout own event loop.

get_input_nonblocking(self)

Return a (next_input_timeout, keys_pressed, raw_keycodes) 
tuple.
 
Use this method if you are implementing your own event loop.
 
When there is input waiting on one of the descriptors returned
by get_input_descriptors() this method should be called to
read and process the input.
 
This method expects to be called in next_input_timeout seconds
(a floating point number) if there is no input waiting.

register_palette(self, l)

Register a list of palette entries.
 
l -- list of (name, foreground, background, mono),
     (name, foreground, background) or
     (name, same_as_other_name) palette entries.
 
calls self.register_palette_entry for each item in l

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

Register a single palette entry.
 
name -- new entry/attribute name
foreground -- foreground colour, one of: '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', 'default' (black if unable to
        use terminal's default)
background -- background colour, one of: 'black', 'dark red',
        'dark green', 'brown', 'dark blue', 'dark magenta',
        'dark cyan', 'light gray', 'default' (light gray if
        unable to use terminal's default)
mono -- monochrome terminal attribute, one of: None (default),
        'bold', 'underline', 'standout', or a tuple containing
        a combination eg. ('bold','underline')

run_wrapper(self, fn, alternate_buffer=True)

Call start to initialize screen, then call fn.  
When fn exits call stop to restore the screen to normal.
 
alternate_buffer -- use alternate screen buffer and restore
        normal screen buffer on exit

set_input_timeouts(self, max_wait=0.5, complete_wait=0.10000000000000001, resize_wait=0.10000000000000001)

Set the get_input timeout values.  All values have are floating
point number of seconds.
 
max_wait -- amount of time in seconds to wait for input when
        there is no input pending
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(self)

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

signal_init(self)

Called in the startup of run wrapper to set the SIGWINCH 
signal handler to self._sigwinch_handler.
 
Override this function to call from main thread in threaded
applications.

signal_restore(self)

Called in the finally block of run wrapper to restore the
SIGWINCH handler to the default handler.
 
Override this function to call from main thread in threaded
applications.

start(self, alternate_buffer=True)

Initialize the screen and input mode.
 
alternate_buffer -- use alternate screen buffer

stop(self)

Restore the screen.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

function curses_display.Screen [back to top]

curses_display.Screen [back to top]

__init__(self)

clear(self)

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

draw_screen(self, (cols, rows), r)

Paint screen with rendered canvas.

get_cols_rows(self)

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

get_input(self, 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:  "\xa1\xea", "\xb2\xd4"
 
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)

register_palette(self, l)

Register a list of palette entries.
 
l -- list of (name, foreground, background, mono),
     (name, foreground, background) or
     (name, same_as_other_name) palette entries.
 
calls self.register_palette_entry for each item in l

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

Register a single palette entry.
 
name -- new entry/attribute name
foreground -- foreground colour, one of: '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', 'default' (black if unable to
        use terminal's default)
background -- background colour, one of: 'black', 'dark red',
        'dark green', 'brown', 'dark blue', 'dark magenta',
        'dark cyan', 'light gray', 'default' (light gray if
        unable to use terminal's default)
mono -- monochrome terminal attribute, one of: None (default),
        'bold', 'underline', 'standout', or a tuple containing
        a combination eg. ('bold','underline')

run_wrapper(self, fn)

Call fn in fullscreen mode.  Return to normal on exit.
 
This function should be called to wrap your main program loop.
Exception tracebacks will be displayed in normal mode.

set_input_timeouts(self, max_wait=0.5, complete_wait=0.10000000000000001, resize_wait=0.10000000000000001)

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. 
 
max_wait -- amount of time in seconds to wait for input when
        there is no input pending
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(self)

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

start(self)

Initialize the screen and input mode.

stop(self)

Restore the screen.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

web_display.Screen [back to top]

__init__(self)

clear(self)

Force the screen to be completely repainted on the next
call to draw_screen().
 
(does nothing for web_display)

draw_screen(self, (cols, rows), r)

Send a screen update to the client.

get_cols_rows(self)

Return the screen size.

get_input(self, raw_keys=False)

Return pending input as a list.

register_palette(self, 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(self, 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(self, fn)

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

set_mouse_tracking(self)

Not yet implemented

start(self)

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(self)

Restore settings and clean up.

Top-level widgets

function Frame [back to top]

class Frame(BoxWidget) [back to top]

Method resolution order:

Frame

BoxWidget

Widget

object

__init__(self, body, header=None, footer=None, focus_part='body')

body -- a box widget for the body of the frame
header -- a flow widget for above the body (or None)
footer -- a flow widget for below the body (or None)
focus_part -- 'header', 'footer' or 'body'

frame_top_bottom(self, (maxcol, maxrow), focus)

Calculate the number of rows for the header and footer.
 
Returns (head rows, foot rows),(orig head, orig foot).
orig head/foot are from rows() calls.

get_body(self)

get_footer(self)

get_header(self)

keypress(self, (maxcol, maxrow), key)

Pass keypress to widget in focus.

mouse_event(self, (maxcol, maxrow), event, button, col, row, focus)

Pass mouse event to appropriate part of frame.
Focus may be changed on button 1 press.

render = cached_render(self, size, focus=False)

set_body(self, body)

set_focus(self, part)

Set the part of the frame that is in focus.
 
part -- 'header', 'footer' or 'body'

set_footer(self, footer)

set_header(self, header)

body

footer

header

selectable(self)

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function Filler [back to top]

class Filler(BoxWidget) [back to top]

Method resolution order:

Filler

BoxWidget

Widget

object

__init__(self, body, valign='middle', height=None, min_height=None)

body -- a flow widget or box widget to be filled around
valign -- one of:
    'top', 'middle', 'bottom'
    ('fixed top', rows)
    ('fixed bottom', rows)
    ('relative', percentage 0=top 100=bottom)
height -- one of:
    None if body is a flow widget
    number of rows high 
    ('fixed bottom', rows)  Only if valign is 'fixed top'
    ('fixed top', rows)  Only if valign is 'fixed bottom'
    ('relative', percentage of total height)
min_height -- one of:
    None if no minimum or if body is a flow widget
    minimum number of rows for the widget when height not fixed
 
If body is a flow widget then height and min_height must be set
to None.
 
Filler widgets will try to satisfy height argument first by
reducing the valign amount when necessary.  If height still 
cannot be satisfied it will also be reduced.

filler_values(self, (maxcol, maxrow), focus)

Return the number of rows to pad on the top and bottom.
 
Override this method to define custom padding behaviour.

get_body(self)

get_cursor_coords(self, (maxcol, maxrow))

Return cursor coords from self.body if any.

get_pref_col(self, (maxcol, maxrow))

Return pref_col from self.body if any.

keypress(self, (maxcol, maxrow), key)

Pass keypress to self.body.

mouse_event(self, (maxcol, maxrow), event, button, col, row, focus)

Pass to self.body.

move_cursor_to_coords(self, (maxcol, maxrow), col, row)

Pass to self.body.

render = cached_render(self, size, focus=False)

selectable(self)

Return selectable from body.

set_body(self, body)

body

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function ListBox [back to top]

class ListBox(BoxWidget) [back to top]

Method resolution order:

ListBox

BoxWidget

Widget

object

__init__(self, body)

body -- a ListWalker-like object that contains
        widgets to be displayed inside the list box

calculate_visible(self, (maxcol, maxrow), focus=False)

Return (middle,top,bottom) or None,None,None.
 
middle -- ( row offset(when +ve) or inset(when -ve),
        focus widget, focus position, focus rows, 
        cursor coords or None )
top -- ( # lines to trim off top, 
        list of (widget, position, rows) tuples above focus
        in order from bottom to top )
bottom -- ( # lines to trim off bottom, 
        list of (widget, position, rows) tuples below focus
        in order from top to bottom )

change_focus(self, (maxcol, maxrow), position, offset_inset=0, coming_from=None, cursor_coords=None, snap_rows=None)

Change the current focus widget.
 
position -- a position compatible with self.body.set_focus
offset_inset_rows -- either the number of rows between the 
  top of the listbox and the start of the focus widget (+ve
  value) or the number of lines of the focus widget hidden off 
  the top edge of the listbox (-ve value) or 0 if the top edge
  of the focus widget is aligned with the top edge of the
  listbox (default if unspecified)
coming_from -- eiter 'above', 'below' or unspecified (None)
cursor_coords -- (x, y) tuple indicating the desired
  column and row for the cursor, a (x,) tuple indicating only
  the column for the cursor, or unspecified (None)
snap_rows -- the maximum number of extra rows to scroll
  when trying to "snap" a selectable focus into the view

ends_visible(self, (maxcol, maxrow), focus=False)

Return a list that may contain 'top' and/or 'bottom'.
 
convenience function for checking whether the top and bottom
of the list are visible

get_focus(self)

Return a (focus widget, focus position) tuple.

get_focus_offset_inset(self, (maxcol, maxrow))

Return (offset rows, inset rows) for focus widget.

keypress(self, (maxcol, maxrow), key)

Move selection through the list elements scrolling when 
necessary. 'up' and 'down' are first passed to widget in focus
in case that widget can handle them. 'page up' and 'page down'
are always handled by the ListBox.
 
Keystrokes handled by this widget are:
 'up'        up one line (or widget)
 'down'      down one line (or widget)
 'page up'   move cursor up one listbox length
 'page down' move cursor down one listbox length

make_cursor_visible(self, (maxcol, maxrow))

Shift the focus widget so that its cursor is visible.

mouse_event(self, (maxcol, maxrow), event, button, col, row, focus)

Pass the event to the contained widgets.
May change focus on button 1 press.

render = cached_render(self, size, focus=False)

set_focus(self, position, coming_from=None)

Set the focus position and try to keep the old focus in view.
 
position -- a position compatible with self.body.set_focus
coming_from -- set to 'above' or 'below' if you know that
               old position is above or below the new position.

set_focus_valign(self, valign)

Set the focus widget's display offset and inset.
 
valign -- one of:
        'top', 'middle', 'bottom'
        ('fixed top', rows)
        ('fixed bottom', rows)
        ('relative', percentage 0=top 100=bottom)

shift_focus(self, (maxcol, maxrow), offset_inset)

Move the location of the current focus relative to the top.
 
offset_inset -- either the number of rows between the 
  top of the listbox and the start of the focus widget (+ve
  value) or the number of lines of the focus widget hidden off 
  the top edge of the listbox (-ve value) or 0 if the top edge
  of the focus widget is aligned with the top edge of the
  listbox

update_pref_col_from_focus(self, (maxcol, maxrow))

Update self.pref_col from the focus widget.

selectable(self)

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

Decorations

function WidgetWrap [back to top]

class WidgetWrap(Widget) [back to top]

Method resolution order:

WidgetWrap

Widget

object

__getattr__(self, name)

Call self.w if name is in Widget interface definition.

__init__(self, w)

w -- widget to wrap, stored as self.w
 
This object will pass the functions defined in Widget interface
definition to self.w.

get_w(self)

render = cached_render(self, size, focus=False)

selectable(self)

set_w(self, w)

w

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function AttrWrap [back to top]

class AttrWrap(Widget) [back to top]

Method resolution order:

AttrWrap

Widget

object

__getattr__(self, name)

Call getattr on wrapped widget.

__init__(self, w, attr, focus_attr=None)

w -- widget to wrap
attr -- attribute to apply to w
focus_attr -- attribute to apply when in focus, if None use attr
 
This object will pass all function calls and variable references
to the wrapped widget.

get_attr(self)

get_focus_attr(self)

get_w(self)

render = cached_render(self, size, focus=False)

selectable(self)

set_attr(self, attr)

set_focus_attr(self, focus_attr)

set_w(self, w)

attr

focus_attr

w

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function Padding [back to top]

class Padding(Widget) [back to top]

Method resolution order:

Padding

Widget

object

__init__(self, w, align, width, min_width=None)

w -- a box, flow or fixed widget to pad on the left and/or right
align -- one of:
    'left', 'center', 'right'
    ('fixed left', columns)
    ('fixed right', columns)
    ('relative', percentage 0=left 100=right)
width -- one of:
    number of columns wide 
    ('fixed right', columns)  Only if align is 'fixed left'
    ('fixed left', columns)  Only if align is 'fixed right'
    ('relative', percentage of total width)
    None   to enable clipping mode
min_width -- the minimum number of columns for w or None
        
Padding widgets will try to satisfy width argument first by
reducing the align amount when necessary.  If width still 
cannot be satisfied it will also be reduced.
 
Clipping Mode:
In clipping mode w is treated as a fixed widget and this 
widget expects to be treated as a flow widget.  w will
be clipped to fit within the space given.  For example,
if align is 'left' then w may be clipped on the right.

get_cursor_coords(self, size)

Return the (x,y) coordinates of cursor within self.w.

get_pref_col(self, size)

Return the preferred column from self.w, or None.

keypress(self, size, key)

Pass keypress to self.w.

mouse_event(self, size, event, button, x, y, focus)

Send mouse event if position is within self.w.

move_cursor_to_coords(self, size, x, y)

Set the cursor position with (x,y) coordinates of self.w.
 
Returns True if move succeeded, False otherwise.

padding_values(self, size, focus)

Return the number of columns to pad on the left and right.
 
Override this method to define custom padding behaviour.

render = cached_render(self, size, focus=False)

rows = cached_rows(self, size, focus=False)

selectable(self)

Return the selectable value of self.w.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function Divider [back to top]

class Divider(FlowWidget) [back to top]

Method resolution order:

Divider

FlowWidget

Widget

object

__init__(self, div_char=' ', top=0, bottom=0)

div_char -- character to repeat across line
top -- number of blank lines above
bottom -- number of blank lines below

render = cached_render(self, size, focus=False)

rows = cached_rows(self, size, focus=False)

selectable(self)

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function LineBox [back to top]

class LineBox(WidgetWrap) [back to top]

Method resolution order:

LineBox

WidgetWrap

Widget

object

__init__(self, w)

Draw a line around w.

__getattr__(self, name)

Call self.w if name is in Widget interface definition.

get_w(self)

render = cached_render(self, size, focus=False)

selectable(self)

set_w(self, w)

w

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function SolidFill [back to top]

class SolidFill(BoxWidget) [back to top]

Method resolution order:

SolidFill

BoxWidget

Widget

object

__init__(self, fill_char=' ')

fill_char -- character to fill area with

render = cached_render(self, size, focus=False)

selectable(self)

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

Composite widgets

function Columns [back to top]

class Columns(Widget) [back to top]

Method resolution order:

Columns

Widget

object

__init__(self, widget_list, dividechars=0, focus_column=None, min_width=1, box_columns=None)

widget_list -- list of flow widgets or list of box widgets
dividechars -- blank characters between columns
focus_column -- index into widget_list of column in focus,
        if None the first selectable widget will be chosen.
min_width -- minimum width for each column before it is hidden
box_columns -- a list of column indexes containing box widgets
        whose maxrow is set to the maximum of the rows 
        required by columns not listed in box_columns.
 
widget_list may also contain tuples such as:
('fixed', width, widget) give this column a fixed width
('weight', weight, widget) give this column a relative weight
 
widgets not in a tuple are the same as ('weight', 1, widget)    
 
box_columns is ignored when this widget is being used as a
box widget because in that case all columns are treated as box
widgets.

column_widths(self, size)

Return a list of column widths.
 
size -- (maxcol,) if self.widget_list contains flow widgets or
        (maxcol, maxrow) if it contains box widgets.

get_cursor_coords(self, size)

Return the cursor coordinates from the focus widget.

get_focus(self)

Return the widget in focus.

get_focus_column(self)

Return the focus column index.

get_pref_col(self, size)

Return the pref col from the column in focus.

keypress(self, size, key)

Pass keypress to the focus column.
 
size -- (maxcol,) if self.widget_list contains flow widgets or
        (maxcol, maxrow) if it contains box widgets.

mouse_event(self, size, event, button, col, row, focus)

Send event to appropriate column.
May change focus on button 1 press.

move_cursor_to_coords(self, size, col, row)

Choose a selectable column to focus based on the coords.

render = cached_render(self, size, focus=False)

rows = cached_rows(self, size, focus=False)

selectable(self)

Return the selectable value of the focus column.

set_focus(self, item)

Set the item in focus.  
 
item -- widget or integer index

set_focus_column(self, num)

Set the column in focus by its index in self.widget_list.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function Pile [back to top]

class Pile(Widget) [back to top]

Method resolution order:

Pile

Widget

object

__init__(self, widget_list, focus_item=None)

widget_list -- list of widgets
focus_item -- widget or integer index, if None the first
        selectable widget will be chosen.
 
widget_list may also contain tuples such as:
('flow', widget) always treat widget as a flow widget
('fixed', height, widget) give this box widget a fixed height
('weight', weight, widget) if the pile is treated as a box
        widget then treat widget as a box widget with a
        height based on its relative weight value, otherwise
        treat widget as a flow widget
 
widgets not in a tuple are the same as ('weight', 1, widget)
 
If the pile is treated as a box widget there must be at least
one 'weight' tuple in widget_list.

get_cursor_coords(self, size)

Return the cursor coordinates of the focus widget.

get_focus(self)

Return the widget in focus.

get_item_rows(self, size, focus)

Return a list of the number of rows used by each widget
in self.item_list.

get_item_size(self, size, i, focus, item_rows=None)

Return a size appropriate for passing to self.widget_list[i]

get_pref_col(self, size)

Return the preferred column for the cursor, or None.

keypress(self, size, key)

Pass the keypress to the widget in focus.
Unhandled 'up' and 'down' keys may cause a focus change.

mouse_event(self, size, event, button, col, row, focus)

Pass the event to the contained widget.
May change focus on button 1 press.

move_cursor_to_coords(self, size, col, row)

Capture pref col and set new focus.

render = cached_render(self, size, focus=False)

rows = cached_rows(self, size, focus=False)

selectable(self)

Return True if the focus item is selectable.

set_focus(self, item)

Set the item in focus.  
 
item -- widget or integer index

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function GridFlow [back to top]

class GridFlow(FlowWidget) [back to top]

Method resolution order:

GridFlow

FlowWidget

Widget

object

__init__(self, cells, cell_width, h_sep, v_sep, align)

cells -- list of flow widgets to display
cell_width -- column width for each cell
h_sep -- blank columns between each cell horizontally
v_sep -- blank rows between cells vertically (if more than
         one row is required to display all the cells)
align -- horizontal alignment of cells, see "align" parameter
         of Padding widget for available options

generate_display_widget(self, (maxcol,))

Actually generate display widget (ignoring cache)

get_cursor_coords(self, (maxcol,))

Get cursor from display widget.

get_display_widget(self, (maxcol,))

Arrange the cells into columns (and possibly a pile) for 
display, input or to calculate rows.

get_pref_col(self, (maxcol,))

Return pref col from display widget.

keypress(self, (maxcol,), key)

Pass keypress to display widget for handling.  
Capture focus changes.

mouse_event(self, (maxcol,), event, button, col, row, focus)

Send mouse event to contained widget.

move_cursor_to_coords(self, (maxcol,), col, row)

Set the widget in focus based on the col + row.

render = cached_render(self, size, focus=False)

rows = cached_rows(self, size, focus=False)

selectable(self)

Return True if the cell in focus is selectable.

set_focus(self, cell)

Set the cell in focus.  
 
cell -- widget or integer index into self.cells

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function BoxAdapter [back to top]

class BoxAdapter(FlowWidget) [back to top]

Method resolution order:

BoxAdapter

FlowWidget

Widget

object

__getattr__(self, name)

Pass calls to box widget.

__init__(self, box_widget, height)

Create a flow widget that contains a box widget
 
box_widget -- box widget
height -- number of rows for box widget

get_cursor_coords(self, (maxcol,))

get_pref_col(self, (maxcol,))

keypress(self, (maxcol,), key)

mouse_event(self, (maxcol,), event, button, col, row, focus)

move_cursor_to_coords(self, (maxcol,), col, row)

render = cached_render(self, size, focus=False)

rows(self, (maxcol,), focus=False)

Return self.height

selectable(self)

Return box widget's selectable value

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function Overlay [back to top]

class Overlay(BoxWidget) [back to top]

Method resolution order:

Overlay

BoxWidget

Widget

object

__init__(self, top_w, bottom_w, align, width, valign, height, min_width=None, min_height=None)

top_w -- a flow, box or fixed widget to overlay "on top"
bottom_w -- a box widget to appear "below" previous widget
align -- one of:
    'left', 'center', 'right'
    ('fixed left', columns)
    ('fixed right', columns)
    ('relative', percentage 0=left 100=right)
width -- one of:
    None if top_w is a fixed widget
    number of columns wide
    ('fixed right', columns)  Only if align is 'fixed left'
    ('fixed left', columns)  Only if align is 'fixed right'
    ('relative', percentage of total width)
valign -- one of:
    'top', 'middle', 'bottom'
    ('fixed top', rows)
    ('fixed bottom', rows)
    ('relative', percentage 0=top 100=bottom)
height -- one of:
    None if top_w is a flow or fixed widget
    number of rows high 
    ('fixed bottom', rows)  Only if valign is 'fixed top'
    ('fixed top', rows)  Only if valign is 'fixed bottom'
    ('relative', percentage of total height)
min_width -- the minimum number of columns for top_w
    when width is not fixed
min_height -- one of:
    minimum number of rows for the widget when height not fixed
 
Overlay widgets behave similarly to Padding and Filler widgets
when determining the size and position of top_w.  bottom_w is
always rendered the full size available "below" top_w.

calculate_padding_filler(self, (maxcol, maxrow), focus)

Return (padding left, right, filler top, bottom).

get_cursor_coords(self, size)

Return cursor coords from top_w, if any.

keypress(self, size, key)

Pass keypress to top_w.

mouse_event(self, size, event, button, col, row, focus)

Pass event to top_w, ignore if outside of top_w.

render = cached_render(self, size, focus=False)

selectable(self)

Return selectable from top_w.

top_w_size(self, size, left, right, top, bottom)

Return the size to pass to top_w.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

Content widgets

function Text [back to top]

class Text(FlowWidget) [back to top]

Method resolution order:

Text

FlowWidget

Widget

object

__init__(self, markup, align='left', wrap='space', layout=None)

markup -- content of text widget, one of:
        plain string -- string is displayed
        ( attr, markup2 ) -- markup2 is given attribute attr
        [ markupA, markupB, ... ] -- list items joined together
align -- align mode for text layout
wrap -- wrap mode for text layout
layout -- layout object to use, defaults to StandardTextLayout

get_line_translation(self, maxcol, ta=None)

Return layout structure for mapping self.text to a canvas.

get_text(self)

Returns (text, attributes).
 
text -- complete string content of text widget
attributes -- run length encoded attributes for text

pack(self, size=None, focus=False)

Return the number of screen columns required for this Text
widget to be displayed without wrapping or clipping, as a 
single element tuple.
 
size -- None for unlimited screen columns or (maxcol,) to
        specify a maximum column size

render = cached_render(self, size, focus=False)

rows = cached_rows(self, size, focus=False)

set_align_mode(self, mode)

Set text alignment / justification.  
 
Valid modes for StandardTextLayout are: 
        'left', 'center' and 'right'

set_layout(self, align, wrap, layout=None)

Set layout object, align and wrap modes.
 
align -- align mode for text layout
wrap -- wrap mode for text layout
layout -- layout object to use, defaults to StandardTextLayout

set_text(self, markup)

Set content of text widget.

set_wrap_mode(self, mode)

Set wrap mode.  
 
Valid modes for StandardTextLayout are :
        'any'   : wrap at any character
        'space' : wrap on space character
        'clip'  : truncate lines instead of wrapping

selectable(self)

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function Edit [back to top]

class Edit(Text) [back to top]

Method resolution order:

Edit

Text

FlowWidget

Widget

object

__init__(self, caption='', edit_text='', multiline=False, align='left', wrap='space', allow_tab=False, edit_pos=None, layout=None)

caption -- markup for caption preceeding edit_text
edit_text -- text string for editing
multiline -- True: 'enter' inserts newline  False: return it
align -- align mode
wrap -- wrap mode
allow_tab -- True: 'tab' inserts 1-8 spaces  False: return it
edit_pos -- initial position for cursor, None:at end
layout -- layout object

get_cursor_coords(self, (maxcol,))

Return the (x,y) coordinates of cursor within widget.

get_edit_text(self)

Return the edit text for this widget.

get_line_translation(self, maxcol, ta=None)

get_pref_col(self, (maxcol,))

Return the preferred column for the cursor, or the
current cursor x value.

get_text(self)

get_text() -> text, attributes
 
text -- complete text of caption and edit_text
attributes -- run length encoded attributes for text

insert_text(self, text)

Insert text at the cursor position and update cursor.

keypress(self, (maxcol,), key)

Handle editing keystrokes, return others.

mouse_event(self, (maxcol,), event, button, x, y, focus)

Move the cursor to the location clicked for button 1.

move_cursor_to_coords(self, (maxcol,), x, y)

Set the cursor position with (x,y) coordinates.
 
Returns True if move succeeded, False otherwise.

position_coords(self, maxcol, pos)

Return (x,y) coordinates for an offset into self.edit_text.

render = cached_render(self, size, focus=False)

selectable(self)

set_caption(self, caption)

Set the caption markup for this widget.

set_edit_pos(self, pos)

Set the cursor position with a self.edit_text offset.

set_edit_text(self, text)

Set the edit text for this widget.

update_text(self)

Deprecated.  Use set_caption and/or set_edit_text instead.
 
Make sure any cached line translation is not reused.

valid_char(self, ch)

Return true for printable characters.

pack(self, size=None, focus=False)

Return the number of screen columns required for this Text
widget to be displayed without wrapping or clipping, as a 
single element tuple.
 
size -- None for unlimited screen columns or (maxcol,) to
        specify a maximum column size

rows = cached_rows(self, size, focus=False)

set_align_mode(self, mode)

Set text alignment / justification.  
 
Valid modes for StandardTextLayout are: 
        'left', 'center' and 'right'

set_layout(self, align, wrap, layout=None)

Set layout object, align and wrap modes.
 
align -- align mode for text layout
wrap -- wrap mode for text layout
layout -- layout object to use, defaults to StandardTextLayout

set_text(self, markup)

Set content of text widget.

set_wrap_mode(self, mode)

Set wrap mode.  
 
Valid modes for StandardTextLayout are :
        'any'   : wrap at any character
        'space' : wrap on space character
        'clip'  : truncate lines instead of wrapping

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function IntEdit [back to top]

class IntEdit(Edit) [back to top]

Method resolution order:

IntEdit

Edit

Text

FlowWidget

Widget

object

__init__(self, caption='', default=None)

caption -- caption markup
default -- default edit value

keypress(self, (maxcol,), key)

Handle editing keystrokes.  Return others.

valid_char(self, ch)

Return true for decimal digits.

value(self)

Return the numeric value of self.edit_text.

get_cursor_coords(self, (maxcol,))

Return the (x,y) coordinates of cursor within widget.

get_edit_text(self)

Return the edit text for this widget.

get_line_translation(self, maxcol, ta=None)

get_pref_col(self, (maxcol,))

Return the preferred column for the cursor, or the
current cursor x value.

get_text(self)

get_text() -> text, attributes
 
text -- complete text of caption and edit_text
attributes -- run length encoded attributes for text

insert_text(self, text)

Insert text at the cursor position and update cursor.

mouse_event(self, (maxcol,), event, button, x, y, focus)

Move the cursor to the location clicked for button 1.

move_cursor_to_coords(self, (maxcol,), x, y)

Set the cursor position with (x,y) coordinates.
 
Returns True if move succeeded, False otherwise.

position_coords(self, maxcol, pos)

Return (x,y) coordinates for an offset into self.edit_text.

render = cached_render(self, size, focus=False)

selectable(self)

set_caption(self, caption)

Set the caption markup for this widget.

set_edit_pos(self, pos)

Set the cursor position with a self.edit_text offset.

set_edit_text(self, text)

Set the edit text for this widget.

update_text(self)

Deprecated.  Use set_caption and/or set_edit_text instead.
 
Make sure any cached line translation is not reused.

pack(self, size=None, focus=False)

Return the number of screen columns required for this Text
widget to be displayed without wrapping or clipping, as a 
single element tuple.
 
size -- None for unlimited screen columns or (maxcol,) to
        specify a maximum column size

rows = cached_rows(self, size, focus=False)

set_align_mode(self, mode)

Set text alignment / justification.  
 
Valid modes for StandardTextLayout are: 
        'left', 'center' and 'right'

set_layout(self, align, wrap, layout=None)

Set layout object, align and wrap modes.
 
align -- align mode for text layout
wrap -- wrap mode for text layout
layout -- layout object to use, defaults to StandardTextLayout

set_text(self, markup)

Set content of text widget.

set_wrap_mode(self, mode)

Set wrap mode.  
 
Valid modes for StandardTextLayout are :
        'any'   : wrap at any character
        'space' : wrap on space character
        'clip'  : truncate lines instead of wrapping

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function Button [back to top]

class Button(WidgetWrap) [back to top]

Method resolution order:

Button

WidgetWrap

Widget

object

__init__(self, label, on_press=None, user_data=None)

label -- markup for button label
on_press -- callback function for button "press"
           on_press( button object, user_data=None)
user_data -- additional param for on_press callback,
           ommited if None for compatibility reasons

get_cursor_coords(self, (maxcol,))

Return the location of the cursor.

get_label(self)

keypress(self, (maxcol,), key)

Call on_press on spage or enter.

mouse_event(self, (maxcol,), event, button, x, y, focus)

Call on_press on button 1 press.

render = cached_render(self, size, focus=False)

selectable(self)

set_label(self, label)

button_left = <urwid.widget.Text object at 0x824330c>

button_right = <urwid.widget.Text object at 0x824332c>

__getattr__(self, name)

Call self.w if name is in Widget interface definition.

get_w(self)

set_w(self, w)

w

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function CheckBox [back to top]

class CheckBox(WidgetWrap) [back to top]

Method resolution order:

CheckBox

WidgetWrap

Widget

object

__init__(self, label, state=False, has_mixed=False, on_state_change=None, user_data=None)

label -- markup for check box label
state -- False, True or "mixed"
has_mixed -- True if "mixed" is a state to cycle through
on_state_change -- callback function for state changes
                   on_state_change( check box, new state,
                                    user_data=None)
user_data -- additional param for on_press callback,
             ommited if None for compatibility reasons

get_label(self)

Return label text.

get_state(self)

Return the state of the checkbox.

keypress(self, (maxcol,), key)

Toggle state on space or enter.

mouse_event(self, (maxcol,), event, button, x, y, focus)

Toggle state on button 1 press.

selectable(self)

set_label(self, label)

Change the check box label.

set_state(self, state, do_callback=True)

Call on_state_change if do_callback is True,
then change the check box state.

toggle_state(self)

Cycle to the next valid state.

reserve_columns = 4

states = {False: <urwid.widget.SelectableIcon object at 0x82431ac>, True: <urwid.widget.SelectableIcon object at 0x824318c>, 'mixed': <urwid.widget.SelectableIcon object at 0x824320c>}

__getattr__(self, name)

Call self.w if name is in Widget interface definition.

get_w(self)

render = cached_render(self, size, focus=False)

set_w(self, w)

w

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

function RadioButton [back to top]

class RadioButton(WidgetWrap) [back to top]

Method resolution order:

RadioButton

WidgetWrap

Widget

object

__init__(self, group, label, state='first True', on_state_change=None, user_data=None)

group -- list for radio buttons in same group
label -- markup for radio button label
state -- False, True, "mixed" or "first True"
on_state_change -- callback function for state changes
                   on_state_change( radio_button, new_state,
                                    user_data=None)
user_data -- additional param for on_press callback,
             ommited if None for compatibility reasons
 
This function will append the new radio button to group.
"first True" will set to True if group is empty.

get_label(self)

Return label text.

get_state(self)

Return the state of the radio button.

keypress(self, (maxcol,), key)

Set state to True on space or enter.

mouse_event(self, (maxcol,), event, button, x, y, focus)

Set state to True on button 1 press.

selectable(self)

set_label(self, label)

Change the check box label.

set_state(self, state, do_callback=True)

Call on_state_change if do_callback is True,
then change the radio button state.
if state is True set all other radio buttons in group to False.

reserve_columns = 4

states = {False: <urwid.widget.SelectableIcon object at 0x824326c>, True: <urwid.widget.SelectableIcon object at 0x824324c>, 'mixed': <urwid.widget.SelectableIcon object at 0x82432cc>}

__getattr__(self, name)

Call self.w if name is in Widget interface definition.

get_w(self)

render = cached_render(self, size, focus=False)

set_w(self, w)

w

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.widget.WidgetMeta'>

Automatic caching of render and rows methods.
 
Class variable no_cache is a list of names of methods to not cache.
Class variable ignore_focus if defined and True indicates that this
widget is not affected by the focus parameter, so it may be ignored
when caching.

Graphics

function BarGraph [back to top]

class BarGraph(BoxWidget) [back to top]

Method resolution order:

BarGraph

BoxWidget

Widget

object

__init__(self, attlist, hatt=None, satt=None)

Create a bar graph with the passed display characteristics.
see set_segment_attributes for a description of the parameters.

calculate_bar_widths(self, (maxcol, maxrow), bardata)

Return a list of bar widths, one for each bar in data.
 
If self.bar_width is None this implementation will stretch 
the bars across the available space specified by maxcol.

calculate_display(self, (maxcol, maxrow))

Calculate display data.

hlines_display(self, disp, top, hlines, maxrow)

Add hlines to display structure represented as bar_type tuple
values:
(bg, 0-5)
bg is the segment that has the hline on it
0-5 is the hline graphic to use where 0 is a regular underscore
and 1-5 are the UTF-8 horizontal scan line characters.

render = cached_render(self, size, focus=False)

selectable(self)

Return