Urwid 1.0.0 Reference

MainLoop & event loops

function MainLoop [back to top]

class MainLoop(object) [back to top]

__init__(self, widget, palette=[], screen=None, handle_mouse=True, input_filter=None, unhandled_input=None, event_loop=None, pop_ups=False)

Simple main loop implementation.
 
widget -- topmost widget used for painting the screen,
    stored as self.widget and may be modified
palette -- initial palette for screen
screen -- screen object or None to use raw_display.Screen,
    stored as self.screen
handle_mouse -- True to process mouse events, passed to
    self.screen
input_filter -- a function to filter input before sending
    it to self.widget, called from self.input_filter
unhandled_input -- a function called when input is not
    handled by self.widget, called from self.unhandled_input
event_loop -- if screen supports external an event loop it
    may be given here, or leave as None to use
    SelectEventLoop, stored as self.event_loop
pop_ups -- True to wrap self.widget with a PopUpTarget
    instance to allow any widget to open a pop-up anywhere on
    the screen
 
This is the standard main loop implementation with a single
screen.
 
The widget passed must be a box widget.

draw_screen(self)

Renter the widgets and paint the screen.  This function is
called automatically from run() but may be called additional
times if repainting is required without also processing input.

entering_idle(self)

This function is called whenever the event loop is about
to enter the idle state.  draw_screen() is called here
to update the screen if anything has changed.

input_filter(self, keys, raw)

This function is passed each all the input events and raw
keystroke values.  These values are passed to the
input_filter function passed to the constructor.  That
function must return a list of keys to be passed to the
widgets to handle.  If no input_filter was defined this
implementation will return all the input events.
 
input -- keyboard or mouse input

process_input(self, keys)

This function will pass keyboard input and mouse events
to self.widget.  This function is called automatically
from the run() method when there is input, but may also be
called to simulate input from the user.
 
keys -- list of input returned from self.screen.get_input()
 
Returns True if any key was handled by a widget or the
unhandled_input() method.         
 
>>> w = _refl("widget")
>>> w.selectable_rval = True
>>> scr = _refl("screen")
>>> scr.get_cols_rows_rval = (10, 5)
>>> ml = MainLoop(w, [], scr)
>>> ml.process_input(['enter', ('mouse drag', 1, 14, 20)])
screen.get_cols_rows()
widget.selectable()
widget.keypress((10, 5), 'enter')
widget.mouse_event((10, 5), 'mouse drag', 1, 14, 20, focus=True)
True

remove_alarm(self, handle)

Remove an alarm.
 
Return True if the handle was found, False otherwise.

remove_watch_file(self, handle)

Remove a watch file.
 
Returns True if the watch file exists, False otherwise.

remove_watch_pipe(self, write_fd)

Close the read end of the pipe and remove the watch created
by watch_pipe().  You are responsible for closing the write
end of the pipe.
 
Returns True if the watch pipe exists, False otherwise

run(self)

Start the main loop handling input events and updating 
the screen.  The loop will continue until an ExitMainLoop 
exception is raised.  
 
This function will call screen.run_wrapper() if screen.start() 
has not already been called.
 
>>> w = _refl("widget")   # _refl prints out function calls
>>> w.render_rval = "fake canvas"  # *_rval is used for return values
>>> scr = _refl("screen")
>>> scr.get_input_descriptors_rval = [42]
>>> scr.get_cols_rows_rval = (20, 10)
>>> scr.started = True
>>> scr._urwid_signals = {}
>>> evl = _refl("event_loop")
>>> evl.enter_idle_rval = 1
>>> evl.watch_file_rval = 2
>>> ml = MainLoop(w, [], scr, event_loop=evl)
>>> ml.run()    # doctest:+ELLIPSIS
screen.set_mouse_tracking()
screen.get_cols_rows()
widget.render((20, 10), focus=True)
screen.draw_screen((20, 10), 'fake canvas')
screen.get_input_descriptors()
event_loop.watch_file(42, <bound method ...>)
event_loop.enter_idle(<bound method ...>)
event_loop.run()
event_loop.remove_enter_idle(1)
event_loop.remove_watch_file(2)
>>> scr.started = False
>>> ml.run()    # doctest:+ELLIPSIS
screen.run_wrapper(<bound method ...>)

set_alarm_at(self, tm, callback, user_data=None)

Schedule at tm time that will call 
callback(main_loop, user_data) from the within the run()
function.
 
Returns a handle that may be passed to remove_alarm()
 
tm -- floating point local time of alarm
callback -- callback(main_loop, user_data) callback function
user_data -- object to pass to callback

set_alarm_in(self, sec, callback, user_data=None)

Schedule an alarm in sec seconds that will call
callback(main_loop, user_data) from the within the run()
function.
 
sec -- floating point seconds until alarm
callback -- callback(main_loop, user_data) callback function
user_data -- object to pass to callback

unhandled_input(self, input)

This function is called with any input that was not handled
by the widgets, and calls the unhandled_input function passed
to the constructor.  If no unhandled_input was defined then
the input will be ignored.
 
input -- keyboard or mouse input
 
The unhandled_input method should return True if it handled
the input.

watch_file(self, fd, callback)

Call callback() when fd has some data to read.  No parameters
are passed to callback.
 
Returns a handle that may be passed to remove_watch_file()
 
fd -- file descriptor to watch for input
callback -- function to call when input is available

watch_pipe(self, callback)

Create a pipe for use by a subprocess or thread to trigger
a callback in the process/thread running the MainLoop.
 
callback -- function to call MainLoop.run thread/process
 
This function returns a file descriptor attached to the
write end of a pipe.  The read end of the pipe is added to
the list of files the event loop is watching. When
data is written to the pipe the callback function will be
called and passed a single value containing data read.
 
This method should be used any time you want to update
widgets from another thread or subprocess.
 
Data may be written to the returned file descriptor with
os.write(fd, data).  Ensure that data is less than 512
bytes (or 4K on Linux) so that the callback will be
triggered just once with the complete value of data
passed in.
 
If the callback returns False then the watch will be
removed and the read end of the pipe will be closed.
You are responsible for closing the write end of the pipe.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

pop_ups

widget

function SelectEventLoop [back to top]

class SelectEventLoop(object) [back to top]

__init__(self)

Event loop based on select.select()
 
>>> import os
>>> rd, wr = os.pipe()
>>> evl = SelectEventLoop()
>>> def step1():
...     print "writing"
...     os.write(wr, "hi".encode('ascii'))
>>> def step2():
...     print os.read(rd, 2).decode('ascii')
...     raise ExitMainLoop
>>> handle = evl.alarm(0, step1)
>>> handle = evl.watch_file(rd, step2)
>>> evl.run()
writing
hi

alarm(self, seconds, callback)

Call callback() given time from from now.  No parameters are
passed to callback.
 
Returns a handle that may be passed to remove_alarm()
 
seconds -- floating point time to wait before calling callback
callback -- function to call from event loop

enter_idle(self, callback)

Add a callback for entering idle.  
 
Returns a handle that may be passed to remove_idle()

remove_alarm(self, handle)

Remove an alarm.
 
Returns True if the alarm exists, False otherwise
 
>>> evl = SelectEventLoop()
>>> handle = evl.alarm(50, lambda: None)
>>> evl.remove_alarm(handle)
True
>>> evl.remove_alarm(handle)
False

remove_enter_idle(self, handle)

Remove an idle callback.
 
Returns True if the handle was removed.

remove_watch_file(self, handle)

Remove an input file.
 
Returns True if the input file exists, False otherwise
 
>>> evl = SelectEventLoop()
>>> handle = evl.watch_file(5, lambda: None)
>>> evl.remove_watch_file(handle)
True
>>> evl.remove_watch_file(handle)
False

run(self)

Start the event loop.  Exit the loop when any callback raises
an exception.  If ExitMainLoop is raised, exit cleanly.
 
>>> import os
>>> rd, wr = os.pipe()
>>> os.write(wr, "data".encode('ascii')) # something to read from rd
4
>>> evl = SelectEventLoop()
>>> def say_hello():
...     print "hello"
>>> def say_waiting():
...     print "waiting"
>>> def exit_clean():
...     print "clean exit"
...     raise ExitMainLoop
>>> def exit_error():
...     1/0
>>> handle = evl.alarm(0.01, exit_clean)
>>> handle = evl.alarm(0.005, say_hello)
>>> evl.enter_idle(say_waiting)
1
>>> evl.run()
waiting
hello
waiting
clean exit
>>> handle = evl.watch_file(rd, exit_clean)
>>> evl.run()
clean exit
>>> evl.remove_watch_file(handle)
True
>>> handle = evl.alarm(0, exit_error)
>>> evl.run()
Traceback (most recent call last):
   ...
ZeroDivisionError: integer division or modulo by zero
>>> handle = evl.watch_file(rd, exit_error)
>>> evl.run()
Traceback (most recent call last):
   ...
ZeroDivisionError: integer division or modulo by zero

watch_file(self, fd, callback)

Call callback() when fd has some data to read.  No parameters
are passed to callback.
 
Returns a handle that may be passed to remove_watch_file()
 
fd -- file descriptor to watch for input
callback -- function to call when input is available

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

function GLibEventLoop [back to top]

class GLibEventLoop(object) [back to top]

__init__(self)

Event loop based on gobject.MainLoop
 
>>> import os
>>> rd, wr = os.pipe()
>>> evl = GLibEventLoop()
>>> def step1():
...     print "writing"
...     os.write(wr, "hi")
>>> def step2():
...     print os.read(rd, 2)
...     raise ExitMainLoop
>>> handle = evl.alarm(0, step1)
>>> handle = evl.watch_file(rd, step2)
>>> evl.run()
writing
hi

alarm(self, seconds, callback)

Call callback() given time from from now.  No parameters are
passed to callback.
 
Returns a handle that may be passed to remove_alarm()
 
seconds -- floating point time to wait before calling callback
callback -- function to call from event loop

enter_idle(self, callback)

Add a callback for entering idle.
 
Returns a handle that may be passed to remove_enter_idle()

handle_exit(self, f)

Decorator that cleanly exits the GLibEventLoop if ExitMainLoop is
thrown inside of the wrapped function.  Store the exception info if 
some other exception occurs, it will be reraised after the loop quits.
f -- function to be wrapped

remove_alarm(self, handle)

Remove an alarm.
 
Returns True if the alarm exists, False otherwise
 
>>> evl = GLibEventLoop()
>>> handle = evl.alarm(50, lambda: None)
>>> evl.remove_alarm(handle)
True
>>> evl.remove_alarm(handle)
False

remove_enter_idle(self, handle)

Remove an idle callback.
 
Returns True if the handle was removed.

remove_watch_file(self, handle)

Remove an input file.
 
Returns True if the input file exists, False otherwise
 
>>> evl = GLibEventLoop()
>>> handle = evl.watch_file(1, lambda: None)
>>> evl.remove_watch_file(handle)
True
>>> evl.remove_watch_file(handle)
False

run(self)

Start the event loop.  Exit the loop when any callback raises
an exception.  If ExitMainLoop is raised, exit cleanly.
 
>>> import os
>>> rd, wr = os.pipe()
>>> os.write(wr, "data") # something to read from rd
4
>>> evl = GLibEventLoop()
>>> def say_hello():
...     print "hello"
>>> def say_waiting():
...     print "waiting"
>>> def exit_clean():
...     print "clean exit"
...     raise ExitMainLoop
>>> def exit_error():
...     1/0
>>> handle = evl.alarm(0.01, exit_clean)
>>> handle = evl.alarm(0.005, say_hello)
>>> evl.enter_idle(say_waiting)
1
>>> evl.run()
waiting
hello
waiting
clean exit
>>> handle = evl.watch_file(rd, exit_clean)
>>> evl.run()
clean exit
>>> evl.remove_watch_file(handle)
True
>>> handle = evl.alarm(0, exit_error)
>>> evl.run()
Traceback (most recent call last):
   ...
ZeroDivisionError: integer division or modulo by zero
>>> handle = evl.watch_file(rd, exit_error)
>>> evl.run()
Traceback (most recent call last):
   ...
ZeroDivisionError: integer division or modulo by zero

watch_file(self, fd, callback)

Call callback() when fd has some data to read.  No parameters
are passed to callback.
 
Returns a handle that may be passed to remove_watch_file()
 
fd -- file descriptor to watch for input
callback -- function to call when input is available

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

function TwistedEventLoop [back to top]

class TwistedEventLoop(object) [back to top]

__init__(self, reactor=None, manage_reactor=True)

Event loop based on Twisted
 
reactor -- reactor object to use, if None defaults to
        twisted.internet.reactor
manage_reactor -- True if you want this event loop to run
        and stop the reactor
 
*** WARNING ***
Twisted's reactor doesn't like to be stopped and run again.
If you need to stop and run your MainLoop, consider setting
manage_reactor=False and take care of running/stopping
the reactor at the beginning/ending of your program yourself.

alarm(self, seconds, callback)

Call callback() given time from from now.  No parameters are
passed to callback.
 
Returns a handle that may be passed to remove_alarm()
 
seconds -- floating point time to wait before calling callback
callback -- function to call from event loop

enter_idle(self, callback)

Add a callback for entering idle.
 
Returns a handle that may be passed to remove_enter_idle()

handle_exit(self, f, enable_idle=True)

Decorator that cleanly exits the TwistedEventLoop if ExitMainLoop is
thrown inside of the wrapped function.  Store the exception info if
some other exception occurs, it will be reraised after the loop quits.
f -- function to be wrapped

remove_alarm(self, handle)

Remove an alarm.
 
Returns True if the alarm exists, False otherwise
 
>>> evl = TwistedEventLoop()
>>> handle = evl.alarm(50, lambda: None)
>>> evl.remove_alarm(handle)
True
>>> evl.remove_alarm(handle)
False

remove_enter_idle(self, handle)

Remove an idle callback.
 
Returns True if the handle was removed.

remove_watch_file(self, handle)

Remove an input file.
 
Returns True if the input file exists, False otherwise
 
>>> evl = TwistedEventLoop()
>>> handle = evl.watch_file(1, lambda: None)
>>> evl.remove_watch_file(handle)
True
>>> evl.remove_watch_file(handle)
False

run(self)

Start the event loop.  Exit the loop when any callback raises
an exception.  If ExitMainLoop is raised, exit cleanly.
 
>>> import os
>>> rd, wr = os.pipe()
>>> os.write(wr, "data") # something to read from rd
4
>>> evl = TwistedEventLoop()
>>> def say_hello_data():
...     print "hello data"
...     os.read(rd, 4)
>>> def say_waiting():
...     print "waiting"
>>> def say_hello():
...     print "hello"
>>> handle = evl.watch_file(rd, say_hello_data)
>>> def say_being_twisted():
...     print "oh I'm messed up"
...     raise ExitMainLoop
>>> handle = evl.alarm(0.0625, say_being_twisted)
>>> handle = evl.alarm(0.03125, say_hello)
>>> evl.enter_idle(say_waiting)
1
>>> evl.run()
hello data
waiting
hello
waiting
oh I'm messed up

watch_file(self, fd, callback)

Call callback() when fd has some data to read.  No parameters
are passed to callback.
 
Returns a handle that may be passed to remove_watch_file()
 
fd -- file descriptor to watch for input
callback -- function to call when input is available

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

Widget base class

function Widget [back to top]

class Widget(object) [back to top]

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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 AttrMap [back to top]

class AttrMap(DelegateToWidgetMixin, WidgetDecoration) [back to top]

Method resolution order:

AttrMap

DelegateToWidgetMixin

WidgetDecoration

Widget

object

__init__(self, w, attr_map, focus_map=None)

w -- widget to wrap (stored as self.original_widget)
attr_map -- attribute to apply to w, or dictionary of attribute mappings
focus_map -- attribute to apply when in focus or dictionary of
    attribute mappings, if None use attr
 
This object will pass all function calls and variable references
to the wrapped widget.
 
>>> AttrMap(Divider(u"!"), 'bright')
<AttrMap flow widget <Divider flow widget '!'> attr_map={None: 'bright'}>
>>> AttrMap(Edit(), 'notfocus', 'focus')
<AttrMap selectable flow widget <Edit selectable flow widget '' edit_pos=0> attr_map={None: 'notfocus'} focus_map={None: 'focus'}>
>>> size = (5,)
>>> am = AttrMap(Text(u"hi"), 'greeting', 'fgreet')
>>> am.render(size, focus=False).content().next() # ... = b in Python 3
[('greeting', None, ...'hi   ')]
>>> am.render(size, focus=True).content().next()
[('fgreet', None, ...'hi   ')]
>>> am2 = AttrMap(Text(('word', u"hi")), {'word':'greeting', None:'bg'})
>>> am2
<AttrMap flow widget <Text flow widget 'hi'> attr_map={'word': 'greeting', None: 'bg'}>
>>> am2.render(size).content().next()
[('greeting', None, ...'hi'), ('bg', None, ...'   ')]

get_attr_map(self)

get_focus_map(self)

render(self, size, focus=False)

Render wrapped widget and apply attribute. Return canvas.

set_attr_map(self, attr_map)

Set the attribute mapping dictionary {from_attr: to_attr, ...}
 
Note this function does not accept a single attribute the way the
constructor does.  You must specify {None: attribute} instead.
 
>> w = AttrMap(Text("hi"), None)
>> w.set_attr({'a':'b'})
>> w
<AttrMap flow widget <Text flow widget 'hi'> attr_map={'a': 'b'}>

set_focus_map(self, focus_map)

Set the focus attribute mapping dictionary 
{from_attr: to_attr, ...}
 
If None this widget will use the attr mapping instead (no change 
when in focus).
 
Note this function does not accept a single attribute the way the
constructor does.  You must specify {None: attribute} instead.
 
>> w = AttrMap(Text("hi"), {})
>> w.set_focus_map({'a':'b'})
>> w
<AttrMap flow widget <Text flow widget 'hi'> attr_map={} focus_map={'a': 'b'}>
>> w.set_focus_map(None)
>> w
<AttrMap flow widget <Text flow widget 'hi'> attr_map={}>

attr_map

focus_map

get_cursor_coords

get_pref_col

keypress

mouse_event

move_cursor_to_coords

pack

rows

selectable

sizing

base_widget

Return the widget without decorations.  If there is only one
Decoration then this is the same as original_widget.
 
>>> t = Text('hello')
>>> wd1 = WidgetDecoration(t)
>>> wd2 = WidgetDecoration(wd1)
>>> wd3 = WidgetDecoration(wd2)
>>> wd3.original_widget is wd2
True
>>> wd3.base_widget is t
True

original_widget

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

__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(WidgetDecoration) [back to top]

Method resolution order:

Padding

WidgetDecoration

Widget

object

__init__(self, w, align='left', width='pack', min_width=None, left=0, right=0)

w -- a box, flow or fixed widget to pad on the left and/or right
    this widget is stored as self.original_widget
align -- one of:
    'left', 'center', 'right'
    ('relative', percentage 0=left 100=right)
width -- one of:
    fixed number of columns for self.original_widget 
    'pack'   try to pack self.original_widget to its ideal size
    ('relative', percentage of total width)
    'clip'   to enable clipping mode for a fixed widget
min_width -- the minimum number of columns for 
    self.original_widget or None
left -- a fixed number of columns to pad on the left
right -- a fixed number of columns to pad on thr right
    
Clipping Mode: (width='clip')
In clipping mode this padding widget will behave as a flow
widget and self.original_widget will be treated as a fixed 
widget.  self.original_widget will will be clipped to fit
the available number of columns.  For example if align is 
'left' then self.original_widget may be clipped on the right.
 
>>> size = (7,)
>>> Padding(Text(u"Head"), ('relative', 20)).render(size).text # ... = b in Python 3
[...' Head  ']
>>> Padding(Divider(u"-"), left=2, right=1).render(size).text
[...'  ---- ']
>>> Padding(Divider(u"*"), 'center', 3).render(size).text
[...'  ***  ']
>>> p=Padding(Text(u"1234"), 'left', 2, None, 1, 1)
>>> p
<Padding flow widget <Text flow widget '1234'> left=1 right=1 width=2>
>>> p.render(size).text   # align against left
[...' 12    ', ...' 34    ']
>>> p.align = 'right'
>>> p.render(size).text   # align against right
[...'    12 ', ...'    34 ']
>>> Padding(Text(u"hi\nthere"), 'right').render(size).text
[...'  hi   ', ...'  there']

get_cursor_coords(self, size)

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

get_pref_col(self, size)

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

keypress(self, size, key)

Pass keypress to self._original_widget.

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

Send mouse event if position is within self._original_widget.

move_cursor_to_coords(self, size, x, y)

Set the cursor position with (x,y) coordinates of self._original_widget.
 
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(self, size, focus=False)

rows(self, size, focus=False)

Return the rows needed for self.original_widget.

sizing(self)

align

Return the padding alignment setting.

width

Return the padding widthment setting.

selectable(self)

base_widget

Return the widget without decorations.  If there is only one
Decoration then this is the same as original_widget.
 
>>> t = Text('hello')
>>> wd1 = WidgetDecoration(t)
>>> wd2 = WidgetDecoration(wd1)
>>> wd3 = WidgetDecoration(wd2)
>>> wd3.original_widget is wd2
True
>>> wd3.base_widget is t
True

original_widget

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

__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(WidgetDecoration) [back to top]

Method resolution order:

Filler

WidgetDecoration

Widget

object

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

body -- a flow widget or box widget to be filled around (stored 
    as self.original_widget)
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, size, focus)

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

get_body = _get_original_widget(self)

get_cursor_coords(self, size)

Return cursor coords from self.original_widget if any.

get_pref_col(self, size)

Return pref_col from self.original_widget if any.

keypress(self, size, key)

Pass keypress to self.original_widget.

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

Pass to self.original_widget.

move_cursor_to_coords(self, size, col, row)

Pass to self.original_widget.

render(self, size, focus=False)

Render self.original_widget with space above and/or below.

selectable(self)

Return selectable from body.

set_body = _set_original_widget(self, original_widget)

sizing(self)

body

base_widget

Return the widget without decorations.  If there is only one
Decoration then this is the same as original_widget.
 
>>> t = Text('hello')
>>> wd1 = WidgetDecoration(t)
>>> wd2 = WidgetDecoration(wd1)
>>> wd3 = WidgetDecoration(wd2)
>>> wd3.original_widget is wd2
True
>>> wd3.base_widget is t
True

original_widget

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

__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=u' ', top=0, bottom=0)

Create a horizontal divider widget.
 
div_char -- character to repeat across line
top -- number of blank lines above
bottom -- number of blank lines below
 
>>> Divider()
<Divider flow widget>
>>> Divider(u'-')
<Divider flow widget '-'>
>>> Divider(u'x', 1, 2)
<Divider flow widget 'x' bottom=2 top=1>

render(self, size, focus=False)

Render the divider as a canvas and return it.
 
>>> Divider().render((10,)).text # ... = b in Python 3
[...'          ']
>>> Divider(u'-', top=1).render((10,)).text
[...'          ', ...'----------']
>>> Divider(u'x', bottom=2).render((5,)).text
[...'xxxxx', ...'     ', ...'     ']

rows(self, size, focus=False)

Return the number of lines that will be rendered.
 
>>> Divider().rows((10,))
1
>>> Divider(u'x', 1, 2).rows((10,))
4

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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(WidgetDecoration, WidgetWrap) [back to top]

Method resolution order:

LineBox

WidgetDecoration

WidgetWrap

DelegateToWidgetMixin

Widget

object

__init__(self, original_widget, title='', tlcorner=None, tline=None, lline=None, trcorner=None, blcorner=None, rline=None, bline=None, brcorner=None)

Draw a line around original_widget.
 
Use 'title' to set an initial title text with will be centered
on top of the box.
 
You can also override the widgets used for the lines/corners:
    tline: top line
    bline: bottom line
    lline: left line
    rline: right line
    tlcorner: top left corner
    trcorner: top right corner
    blcorner: bottom left corner
    brcorner: bottom right corner

format_title(self, text)

set_title(self, text)

ACS_HLINE = u'\u2500'

ACS_LLCORNER = u'\u2514'

ACS_LRCORNER = u'\u2518'

ACS_ULCORNER = u'\u250c'

ACS_URCORNER = u'\u2510'

ACS_VLINE = u'\u2502'

selectable(self)

sizing(self)

base_widget

Return the widget without decorations.  If there is only one
Decoration then this is the same as original_widget.
 
>>> t = Text('hello')
>>> wd1 = WidgetDecoration(t)
>>> wd2 = WidgetDecoration(wd1)
>>> wd3 = WidgetDecoration(wd2)
>>> wd3.original_widget is wd2
True
>>> wd3.base_widget is t
True

original_widget

w

render(self, size, focus=False)

get_cursor_coords

get_pref_col

keypress

mouse_event

move_cursor_to_coords

pack

rows

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

__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=' ')

Create a box widget that will fill an area with a single 
character.
 
fill_char -- character to fill area with
 
>>> SolidFill(u'8')
<SolidFill box widget '8'>

render(self, size, focus=False)

Render the Fill as a canvas and return it.
 
>>> SolidFill().render((4,2)).text # ... = b in Python 3
[...'    ', ...'    ']
>>> SolidFill('#').render((5,3)).text
[...'#####', ...'#####', ...'#####']

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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.

Container 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, size, 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_focus(self)

Return the part of the frame that is in focus.
 
Will be one of 'header', 'footer' or 'body'.

get_footer(self)

get_header(self)

keypress(self, size, key)

Pass keypress to widget in focus.

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

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

render(self, size, focus=False)

Render frame and return it.

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

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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, size, 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, size, 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 -- 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, size, 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_cursor_coords(self, size)

get_focus(self)

Return a (focus widget, focus position) tuple.

get_focus_offset_inset(self, size)

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

keypress(self, size, 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, size)

Shift the focus widget so that its cursor is visible.

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

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

render(self, size, focus=False)

Render listbox and return canvas.

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, size, 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, size)

Update self.pref_col from the focus widget.

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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 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 which is not
    designated as flow widget in widget_list.
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:
('flow', widget) always treat widget as a flow widget
('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, focus=False)

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(self, size, focus=False)

Render columns and return canvas.
 
size -- (maxcol,) if self.widget_list contains flow widgets or
    (maxcol, maxrow) if it contains box widgets.

rows(self, size, focus=False)

Return the number of rows required by the columns.
Only makes sense if self.widget_list contains flow widgets.

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.

contents

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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(self, size, focus=False)

Render all widgets in self.widget_list and return the results
stacked one on top of the next.

rows(self, size, focus=False)

Return the number of rows required for this widget.

selectable(self)

Return True if the focus item is selectable.

set_focus(self, item)

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

contents

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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, size)

Actually generate display widget (ignoring cache)

get_cursor_coords(self, size)

Get cursor from display widget.

get_display_widget(self, size)

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

get_focus(self)

Return the widget in focus.

get_pref_col(self, size)

Return pref col from display widget.

keypress(self, size, key)

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

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

Send mouse event to contained widget.

move_cursor_to_coords(self, size, col, row)

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

render(self, size, focus=False)

Use display widget to render.

rows(self, size, focus=False)

Return rows used by this widget.

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

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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(WidgetDecoration) [back to top]

Method resolution order:

BoxAdapter

WidgetDecoration

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 (stored as self.original_widget)
height -- number of rows for box widget
 
>>> BoxAdapter(SolidFill(u"x"), 5) # 5-rows of x's
<BoxAdapter flow widget <SolidFill box widget 'x'> height=5>

get_cursor_coords(self, size)

# The next few functions simply tack-on our height and pass through
# to self._original_widget

get_pref_col(self, size)

keypress(self, size, key)

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

move_cursor_to_coords(self, size, col, row)

render(self, size, focus=False)

rows(self, size, focus=False)

Return the predetermined height (behave like a flow widget)
 
>>> BoxAdapter(SolidFill(u"x"), 5).rows((20,))
5

sizing(self)

box_widget

selectable(self)

base_widget

Return the widget without decorations.  If there is only one
Decoration then this is the same as original_widget.
 
>>> t = Text('hello')
>>> wd1 = WidgetDecoration(t)
>>> wd2 = WidgetDecoration(wd1)
>>> wd3 = WidgetDecoration(wd2)
>>> wd3.original_widget is wd2
True
>>> wd3.base_widget is t
True

original_widget

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

__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, size, 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(self, size, focus=False)

Render top_w overlayed on bottom_w.

selectable(self)

Return selectable from top_w.

set_overlay_parameters(self, align, width, valign, height, min_width=None, min_height=None)

Adjust the overlay size and position parameters.
 
See __init__() for a description of the parameters.

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

Return the size to pass to top_w.

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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
 
>>> Text(u"Hello")
<Text flow widget 'Hello'>
>>> t = Text(('bold', u"stuff"), 'right', 'any')
>>> t
<Text flow widget 'stuff' align='right' wrap='any'>
>>> print t.text
stuff
>>> t.attrib
[('bold', 5)]

get_line_translation(self, maxcol, ta=None)

Return layout structure used to map self.text to a canvas.
This method is used internally, but may be useful for
debugging custom layout classes.
 
maxcol -- columns available for display
ta -- None or the (text, attr) tuple returned from
      get_text()

get_text(self)

Returns (text, attributes).
 
text -- complete string content (unicode) of text widget
attributes -- run length encoded attributes for text
 
>>> Text(u"Hello").get_text() # ... = u in Python 2
(...'Hello', [])
>>> Text(('bright', u"Headline")).get_text()
(...'Headline', [('bright', 8)])
>>> Text([('a', u"one"), u"two", ('b', u"three")]).get_text()
(...'onetwothree', [('a', 3), (None, 3), ('b', 5)])

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

Return the number of screen columns and rows 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
 
>>> Text(u"important things").pack()
(16, 1)
>>> Text(u"important things").pack((15,))
(9, 2)
>>> Text(u"important things").pack((8,))
(8, 2)

render(self, size, focus=False)

Render contents with wrapping and alignment.  Return canvas.
 
>>> Text(u"important things").render((18,)).text # ... = b in Python 3
[...'important things  ']
>>> Text(u"important things").render((11,)).text
[...'important  ', ...'things     ']

rows(self, size, focus=False)

Return the number of rows the rendered text spans.
 
>>> Text(u"important things").rows((18,))
1
>>> Text(u"important things").rows((11,))
2

set_align_mode(self, mode)

Set text alignment / justification.
 
Valid modes for StandardTextLayout are:
    'left', 'center' and 'right'
 
>>> t = Text(u"word")
>>> t.set_align_mode('right')
>>> t.align
'right'
>>> t.render((10,)).text # ... = b in Python 3
[...'      word']
>>> t.align = 'center'
>>> t.render((10,)).text
[...'   word   ']
>>> t.align = 'somewhere'
Traceback (most recent call last):
TextError: Alignment mode 'somewhere' not supported.

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
 
>>> t = Text(u"hi")
>>> t.set_layout('right', 'clip')
>>> t
<Text flow widget 'hi' align='right' wrap='clip'>

set_text(self, markup)

Set content of text widget.
 
markup -- see __init__() for description.
 
>>> t = Text(u"foo")
>>> print t.text
foo
>>> t.set_text(u"bar")
>>> print t.text
bar
>>> t.text = u"baz"  # not supported because text stores text but set_text() takes markup
Traceback (most recent call last):
AttributeError: can't set attribute

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
 
>>> t = Text(u"some words")
>>> t.render((6,)).text # ... = b in Python 3
[...'some  ', ...'words ']
>>> t.set_wrap_mode('clip')
>>> t.wrap
'clip'
>>> t.render((6,)).text
[...'some w']
>>> t.wrap = 'any'  # Urwid 0.9.9 or later
>>> t.render((6,)).text
[...'some w', ...'ords  ']
>>> t.wrap = 'somehow'
Traceback (most recent call last):
TextError: Wrap mode 'somehow' not supported.

align

attrib

layout

text

wrap

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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=u'', edit_text=u'', multiline=False, align='left', wrap='space', allow_tab=False, edit_pos=None, layout=None, mask=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
mask -- character to mask away text with, None means no masking
 
>>> Edit()
<Edit selectable flow widget '' edit_pos=0>
>>> Edit(u"Y/n? ", u"yes")
<Edit selectable flow widget 'yes' caption='Y/n? ' edit_pos=3>
>>> Edit(u"Name ", u"Smith", edit_pos=1)
<Edit selectable flow widget 'Smith' caption='Name ' edit_pos=1>
>>> Edit(u"", u"3.14", align='right')
<Edit selectable flow widget '3.14' align='right' edit_pos=4>

get_cursor_coords(self, size)

Return the (x,y) coordinates of cursor within widget.
 
>>> Edit("? ","yes").get_cursor_coords((10,))
(5, 0)

get_edit_text(self)

Return the edit text for this widget.
 
>>> e = Edit(u"What? ", u"oh, nothing.")
>>> print e.get_edit_text()
oh, nothing.
>>> print e.edit_text
oh, nothing.

get_line_translation(self, maxcol, ta=None)

get_pref_col(self, size)

Return the preferred column for the cursor, or the
current cursor x value.  May also return 'left' or 'right'
to indicate the leftmost or rightmost column available.
 
This method is used internally and by other widgets when
moving the cursor up or down between widgets so that the 
column selected is one that the user would expect.
 
>>> size = (10,)
>>> Edit().get_pref_col(size)
0
>>> e = Edit("","word")
>>> e.get_pref_col(size)
4
>>> e.keypress(size, 'left')
>>> e.get_pref_col(size)
3
>>> e.keypress(size, 'end')
>>> e.get_pref_col(size)
'right'
>>> e = Edit("","2\nwords")
>>> e.keypress(size, 'left')
>>> e.keypress(size, 'up')
>>> e.get_pref_col(size)
4
>>> e.keypress(size, 'left')
>>> e.get_pref_col(size)
0

get_text(self)

Returns (text, attributes).
 
text -- complete text of caption and edit_text, maybe masked away
attributes -- run length encoded attributes for text
 
>>> Edit("What? ","oh, nothing.").get_text() # ... = u in Python 2
(...'What? oh, nothing.', [])
>>> Edit(('bright',"user@host:~$ "),"ls").get_text()
(...'user@host:~$ ls', [('bright', 13)])

insert_text(self, text)

Insert text at the cursor position and update cursor.
This method is used by the keypress() method when inserting
one or more characters into edit_text.
 
>>> e = Edit(u"", u"42")
>>> e.insert_text(u".5")
>>> e
<Edit selectable flow widget '42.5' edit_pos=4>
>>> e.set_edit_pos(2)
>>> e.insert_text(u"a")
>>> print e.edit_text
42a.5

insert_text_result(self, text)

Return result of insert_text(text) without actually performing the
insertion.  Handy for pre-validation.

keypress(self, size, key)

Handle editing keystrokes, return others.
 
>>> e, size = Edit(), (20,)
>>> e.keypress(size, 'x')
>>> e.keypress(size, 'left')
>>> e.keypress(size, '1')
>>> print e.edit_text
1x
>>> e.keypress(size, 'backspace')
>>> e.keypress(size, 'end')
>>> e.keypress(size, '2')
>>> print e.edit_text
x2
>>> e.keypress(size, 'shift f1')
'shift f1'

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

Move the cursor to the location clicked for button 1.
 
>>> size = (20,)
>>> e = Edit("","words here")
>>> e.mouse_event(size, 'mouse press', 1, 2, 0, True)
True
>>> e.edit_pos
2

move_cursor_to_coords(self, size, x, y)

Set the cursor position with (x,y) coordinates.
Returns True if move succeeded, False otherwise.
 
>>> size = (10,)
>>> e = Edit("","edit\ntext")
>>> e.move_cursor_to_coords(size, 5, 0)
True
>>> e.edit_pos
4
>>> e.move_cursor_to_coords(size, 5, 3)
False
>>> e.move_cursor_to_coords(size, 0, 1)
True
>>> e.edit_pos
5

position_coords(self, maxcol, pos)

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

render(self, size, focus=False)

Render edit widget and return canvas.  Include cursor when in
focus.
 
>>> c = Edit("? ","yes").render((10,), focus=True)
>>> c.text # ... = b in Python 3
[...'? yes     ']
>>> c.cursor
(5, 0)

selectable(self)

set_caption(self, caption)

Set the caption markup for this widget.
 
caption -- see Text.__init__() for description of markup
 
>>> e = Edit("")
>>> e.set_caption("cap1")
>>> print e.caption
cap1
>>> e.set_caption(('bold', "cap2"))
>>> print e.caption
cap2
>>> e.attrib
[('bold', 4)]
>>> e.caption = "cap3"  # not supported because caption stores text but set_caption() takes markup
Traceback (most recent call last):
AttributeError: can't set attribute

set_edit_pos(self, pos)

Set the cursor position with a self.edit_text offset.  
Clips pos to [0, len(edit_text)].
 
>>> e = Edit(u"", u"word")
>>> e.edit_pos
4
>>> e.set_edit_pos(2)
>>> e.edit_pos
2
>>> e.edit_pos = -1  # Urwid 0.9.9 or later
>>> e.edit_pos
0
>>> e.edit_pos = 20
>>> e.edit_pos
4

set_edit_text(self, text)

Set the edit text for this widget.
 
>>> e = Edit()
>>> e.set_edit_text(u"yes")
>>> print e.edit_text
yes
>>> e
<Edit selectable flow widget 'yes' edit_pos=0>
>>> e.edit_text = u"no"  # Urwid 0.9.9 or later
>>> print e.edit_text
no

set_mask(self, mask)

Set the character for masking text away. Empty means no masking.

set_text(self, markup)

Not supported by Edit widget.
 
>>> Edit().set_text("test")
Traceback (most recent call last):
EditError: set_text() not supported.  Use set_caption() or set_edit_text() instead.

update_text(self)

No longer supported.
 
>>> Edit().update_text()
Traceback (most recent call last):
EditError: update_text() has been removed.  Use set_caption() or set_edit_text() instead.

valid_char(self, ch)

Return true for printable characters.

caption

edit_pos

edit_text

Return the edit text for this widget.
 
>>> e = Edit(u"What? ", u"oh, nothing.")
>>> print e.get_edit_text()
oh, nothing.
>>> print e.edit_text
oh, nothing.

signals = ['change']

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

Return the number of screen columns and rows 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
 
>>> Text(u"important things").pack()
(16, 1)
>>> Text(u"important things").pack((15,))
(9, 2)
>>> Text(u"important things").pack((8,))
(8, 2)

rows(self, size, focus=False)

Return the number of rows the rendered text spans.
 
>>> Text(u"important things").rows((18,))
1
>>> Text(u"important things").rows((11,))
2

set_align_mode(self, mode)

Set text alignment / justification.
 
Valid modes for StandardTextLayout are:
    'left', 'center' and 'right'
 
>>> t = Text(u"word")
>>> t.set_align_mode('right')
>>> t.align
'right'
>>> t.render((10,)).text # ... = b in Python 3
[...'      word']
>>> t.align = 'center'
>>> t.render((10,)).text
[...'   word   ']
>>> t.align = 'somewhere'
Traceback (most recent call last):
TextError: Alignment mode 'somewhere' not supported.

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
 
>>> t = Text(u"hi")
>>> t.set_layout('right', 'clip')
>>> t
<Text flow widget 'hi' align='right' wrap='clip'>

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
 
>>> t = Text(u"some words")
>>> t.render((6,)).text # ... = b in Python 3
[...'some  ', ...'words ']
>>> t.set_wrap_mode('clip')
>>> t.wrap
'clip'
>>> t.render((6,)).text
[...'some w']
>>> t.wrap = 'any'  # Urwid 0.9.9 or later
>>> t.render((6,)).text
[...'some w', ...'ords  ']
>>> t.wrap = 'somehow'
Traceback (most recent call last):
TextError: Wrap mode 'somehow' not supported.

align

attrib

layout

text

wrap

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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
 
>>> IntEdit(u"", 42)
<IntEdit selectable flow widget '42' edit_pos=2>

keypress(self, size, key)

Handle editing keystrokes.  Remove leading zeros.
 
>>> e, size = IntEdit(u"", 5002), (10,)
>>> e.keypress(size, 'home')
>>> e.keypress(size, 'delete')
>>> print e.edit_text
002
>>> e.keypress(size, 'end')
>>> print e.edit_text
2

valid_char(self, ch)

Return true for decimal digits.

value(self)

Return the numeric value of self.edit_text.
 
>>> e, size = IntEdit(), (10,)
>>> e.keypress(size, '5')
>>> e.keypress(size, '1')
>>> e.value() == 51
True

get_cursor_coords(self, size)

Return the (x,y) coordinates of cursor within widget.
 
>>> Edit("? ","yes").get_cursor_coords((10,))
(5, 0)

get_edit_text(self)

Return the edit text for this widget.
 
>>> e = Edit(u"What? ", u"oh, nothing.")
>>> print e.get_edit_text()
oh, nothing.
>>> print e.edit_text
oh, nothing.

get_line_translation(self, maxcol, ta=None)

get_pref_col(self, size)

Return the preferred column for the cursor, or the
current cursor x value.  May also return 'left' or 'right'
to indicate the leftmost or rightmost column available.
 
This method is used internally and by other widgets when
moving the cursor up or down between widgets so that the 
column selected is one that the user would expect.
 
>>> size = (10,)
>>> Edit().get_pref_col(size)
0
>>> e = Edit("","word")
>>> e.get_pref_col(size)
4
>>> e.keypress(size, 'left')
>>> e.get_pref_col(size)
3
>>> e.keypress(size, 'end')
>>> e.get_pref_col(size)
'right'
>>> e = Edit("","2\nwords")
>>> e.keypress(size, 'left')
>>> e.keypress(size, 'up')
>>> e.get_pref_col(size)
4
>>> e.keypress(size, 'left')
>>> e.get_pref_col(size)
0

get_text(self)

Returns (text, attributes).
 
text -- complete text of caption and edit_text, maybe masked away
attributes -- run length encoded attributes for text
 
>>> Edit("What? ","oh, nothing.").get_text() # ... = u in Python 2
(...'What? oh, nothing.', [])
>>> Edit(('bright',"user@host:~$ "),"ls").get_text()
(...'user@host:~$ ls', [('bright', 13)])

insert_text(self, text)

Insert text at the cursor position and update cursor.
This method is used by the keypress() method when inserting
one or more characters into edit_text.
 
>>> e = Edit(u"", u"42")
>>> e.insert_text(u".5")
>>> e
<Edit selectable flow widget '42.5' edit_pos=4>
>>> e.set_edit_pos(2)
>>> e.insert_text(u"a")
>>> print e.edit_text
42a.5

insert_text_result(self, text)

Return result of insert_text(text) without actually performing the
insertion.  Handy for pre-validation.

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

Move the cursor to the location clicked for button 1.
 
>>> size = (20,)
>>> e = Edit("","words here")
>>> e.mouse_event(size, 'mouse press', 1, 2, 0, True)
True
>>> e.edit_pos
2

move_cursor_to_coords(self, size, x, y)

Set the cursor position with (x,y) coordinates.
Returns True if move succeeded, False otherwise.
 
>>> size = (10,)
>>> e = Edit("","edit\ntext")
>>> e.move_cursor_to_coords(size, 5, 0)
True
>>> e.edit_pos
4
>>> e.move_cursor_to_coords(size, 5, 3)
False
>>> e.move_cursor_to_coords(size, 0, 1)
True
>>> e.edit_pos
5

position_coords(self, maxcol, pos)

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

render(self, size, focus=False)

Render edit widget and return canvas.  Include cursor when in
focus.
 
>>> c = Edit("? ","yes").render((10,), focus=True)
>>> c.text # ... = b in Python 3
[...'? yes     ']
>>> c.cursor
(5, 0)

selectable(self)

set_caption(self, caption)

Set the caption markup for this widget.
 
caption -- see Text.__init__() for description of markup
 
>>> e = Edit("")
>>> e.set_caption("cap1")
>>> print e.caption
cap1
>>> e.set_caption(('bold', "cap2"))
>>> print e.caption
cap2
>>> e.attrib
[('bold', 4)]
>>> e.caption = "cap3"  # not supported because caption stores text but set_caption() takes markup
Traceback (most recent call last):
AttributeError: can't set attribute

set_edit_pos(self, pos)

Set the cursor position with a self.edit_text offset.  
Clips pos to [0, len(edit_text)].
 
>>> e = Edit(u"", u"word")
>>> e.edit_pos
4
>>> e.set_edit_pos(2)
>>> e.edit_pos
2
>>> e.edit_pos = -1  # Urwid 0.9.9 or later
>>> e.edit_pos
0
>>> e.edit_pos = 20
>>> e.edit_pos
4

set_edit_text(self, text)

Set the edit text for this widget.
 
>>> e = Edit()
>>> e.set_edit_text(u"yes")
>>> print e.edit_text
yes
>>> e
<Edit selectable flow widget 'yes' edit_pos=0>
>>> e.edit_text = u"no"  # Urwid 0.9.9 or later
>>> print e.edit_text
no

set_mask(self, mask)

Set the character for masking text away. Empty means no masking.

set_text(self, markup)

Not supported by Edit widget.
 
>>> Edit().set_text("test")
Traceback (most recent call last):
EditError: set_text() not supported.  Use set_caption() or set_edit_text() instead.

update_text(self)

No longer supported.
 
>>> Edit().update_text()
Traceback (most recent call last):
EditError: update_text() has been removed.  Use set_caption() or set_edit_text() instead.

caption

edit_pos

edit_text

Return the edit text for this widget.
 
>>> e = Edit(u"What? ", u"oh, nothing.")
>>> print e.get_edit_text()
oh, nothing.
>>> print e.edit_text
oh, nothing.

signals = ['change']

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

Return the number of screen columns and rows 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
 
>>> Text(u"important things").pack()
(16, 1)
>>> Text(u"important things").pack((15,))
(9, 2)
>>> Text(u"important things").pack((8,))
(8, 2)

rows(self, size, focus=False)

Return the number of rows the rendered text spans.
 
>>> Text(u"important things").rows((18,))
1
>>> Text(u"important things").rows((11,))
2

set_align_mode(self, mode)

Set text alignment / justification.
 
Valid modes for StandardTextLayout are:
    'left', 'center' and 'right'
 
>>> t = Text(u"word")
>>> t.set_align_mode('right')
>>> t.align
'right'
>>> t.render((10,)).text # ... = b in Python 3
[...'      word']
>>> t.align = 'center'
>>> t.render((10,)).text
[...'   word   ']
>>> t.align = 'somewhere'
Traceback (most recent call last):
TextError: Alignment mode 'somewhere' not supported.

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
 
>>> t = Text(u"hi")
>>> t.set_layout('right', 'clip')
>>> t
<Text flow widget 'hi' align='right' wrap='clip'>

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
 
>>> t = Text(u"some words")
>>> t.render((6,)).text # ... = b in Python 3
[...'some  ', ...'words ']
>>> t.set_wrap_mode('clip')
>>> t.wrap
'clip'
>>> t.render((6,)).text
[...'some w']
>>> t.wrap = 'any'  # Urwid 0.9.9 or later
>>> t.render((6,)).text
[...'some w', ...'ords  ']
>>> t.wrap = 'somehow'
Traceback (most recent call last):
TextError: Wrap mode 'somehow' not supported.

align

attrib

layout

text

wrap

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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

DelegateToWidgetMixin

Widget

object

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

label -- markup for button label
on_press, user_data -- shorthand for connect_signal()
    function call for a single callback
 
Signals supported: 'click'
Register signal handler with:
  connect_signal(button, 'click', callback [,user_data])
where callback is callback(button [,user_data])
Unregister signal handlers with:
  disconnect_signal(button, 'click', callback [,user_data])
 
>>> Button(u"Ok")
<Button selectable widget 'Ok'>
>>> b = Button("Cancel")
>>> b.render((15,), focus=True).text # ... = b in Python 3
[...'< Cancel      >']

get_label(self)

Return label text.
 
>>> b = Button(u"Ok")
>>> print b.get_label()
Ok
>>> print b.label  # Urwid 0.9.9 or later
Ok

keypress(self, size, key)

Send 'click' signal on 'activate' command.
 
>>> assert Button._command_map[' '] == 'activate'
>>> assert Button._command_map['enter'] == 'activate'
>>> size = (15,)
>>> b = Button(u"Cancel")
>>> clicked_buttons = []
>>> def handle_click(button):
...     clicked_buttons.append(button.label)
>>> connect_signal(b, 'click', handle_click)
>>> b.keypress(size, 'enter')
>>> b.keypress(size, ' ')
>>> clicked_buttons # ... = u in Python 2
[...'Cancel', ...'Cancel']

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

Send 'click' signal on button 1 press.
 
>>> size = (15,)
>>> b = Button(u"Ok")
>>> clicked_buttons = []
>>> def handle_click(button):
...     clicked_buttons.append(button.label)
>>> connect_signal(b, 'click', handle_click)
>>> b.mouse_event(size, 'mouse press', 1, 4, 0, True)
True
>>> b.mouse_event(size, 'mouse press', 2, 4, 0, True) # ignored
False
>>> clicked_buttons # ... = u in Python 2
[...'Ok']

set_label(self, label)

Change the button label.
 
label -- markup for button label
 
>>> b = Button("Ok")
>>> b.set_label(u"Yup yup")
>>> b
<Button selectable widget 'Yup yup'>

label

Return label text.
 
>>> b = Button(u"Ok")
>>> print b.get_label()
Ok
>>> print b.label  # Urwid 0.9.9 or later
Ok

button_left = <Text flow widget b'<'>

button_right = <Text flow widget b'>'>

signals = ['click']

w

render(self, size, focus=False)

get_cursor_coords

get_pref_col

move_cursor_to_coords

pack

rows

selectable

sizing

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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

DelegateToWidgetMixin

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, user_data -- shorthand for connect_signal()
    function call for a single callback
 
Signals supported: 'change'
Register signal handler with:
  connect_signal(check_box, 'change', callback [,user_data])
where callback is callback(check_box, new_state [,user_data])
Unregister signal handlers with:
  disconnect_signal(check_box, 'change', callback [,user_data])
 
>>> CheckBox(u"Confirm")
<CheckBox selectable widget 'Confirm' state=False>
>>> CheckBox(u"Yogourt", "mixed", True)
<CheckBox selectable widget 'Yogourt' state='mixed'>
>>> cb = CheckBox(u"Extra onions", True)
>>> cb
<CheckBox selectable widget 'Extra onions' state=True>
>>> cb.render((20,), focus=True).text # ... = b in Python 3
[...'[X] Extra onions    ']

get_label(self)

Return label text.
 
>>> cb = CheckBox(u"Seriously")
>>> print cb.get_label()
Seriously
>>> print cb.label  # Urwid 0.9.9 or later
Seriously
>>> cb.set_label([('bright_attr', u"flashy"), u" normal"])
>>> print cb.label  #  only text is returned
flashy normal

get_state(self)

Return the state of the checkbox.

keypress(self, size, key)

Toggle state on 'activate' command.  
 
>>> assert CheckBox._command_map[' '] == 'activate'
>>> assert CheckBox._command_map['enter'] == 'activate'
>>> size = (10,)
>>> cb = CheckBox('press me')
>>> cb.state
False
>>> cb.keypress(size, ' ')
>>> cb.state
True
>>> cb.keypress(size, ' ')
>>> cb.state
False

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

Toggle state on button 1 press.
 
>>> size = (20,)
>>> cb = CheckBox("clickme")
>>> cb.state
False
>>> cb.mouse_event(size, 'mouse press', 1, 2, 0, True)
True
>>> cb.state
True

set_label(self, label)

Change the check box label.
 
label -- markup for label.  See Text widget for description
of text markup.
 
>>> cb = CheckBox(u"foo")
>>> cb
<CheckBox selectable widget 'foo' state=False>
>>> cb.set_label(('bright_attr', u"bar"))
>>> cb
<CheckBox selectable widget 'bar' state=False>

set_state(self, state, do_callback=True)

Set the CheckBox state.
 
state -- True, False or "mixed"
do_callback -- False to supress signal from this change
 
>>> changes = []
>>> def callback_a(cb, state, user_data): 
...     changes.append("A %r %r" % (state, user_data))
>>> def callback_b(cb, state): 
...     changes.append("B %r" % state)
>>> cb = CheckBox('test', False, False)
>>> connect_signal(cb, 'change', callback_a, "user_a")
>>> connect_signal(cb, 'change', callback_b)
>>> cb.set_state(True) # both callbacks will be triggered
>>> cb.state
True
>>> disconnect_signal(cb, 'change', callback_a, "user_a")
>>> cb.state = False  # Urwid 0.9.9 or later
>>> cb.state
False
>>> cb.set_state(True)
>>> cb.state
True
>>> cb.set_state(False, False) # don't send signal
>>> changes
["A True 'user_a'", 'B True', 'B False', 'B True']

toggle_state(self)

Cycle to the next valid state.
 
>>> cb = CheckBox("3-state", has_mixed=True)
>>> cb.state
False
>>> cb.toggle_state()
>>> cb.state
True
>>> cb.toggle_state()
>>> cb.state
'mixed'
>>> cb.toggle_state()
>>> cb.state
False

label

Return label text.
 
>>> cb = CheckBox(u"Seriously")
>>> print cb.get_label()
Seriously
>>> print cb.label  # Urwid 0.9.9 or later
Seriously
>>> cb.set_label([('bright_attr', u"flashy"), u" normal"])
>>> print cb.label  #  only text is returned
flashy normal

state

Return the state of the checkbox.

reserve_columns = 4

signals = ['change']

states = {False: <SelectableIcon selectable flow widget b'[ ]'>, True: <SelectableIcon selectable flow widget b'[X]'>, 'mixed': <SelectableIcon selectable flow widget b'[#]'>}

w

render(self, size, focus=False)

get_cursor_coords

get_pref_col

move_cursor_to_coords

pack

rows

selectable

sizing

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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(CheckBox) [back to top]

Method resolution order:

RadioButton

CheckBox

WidgetWrap

DelegateToWidgetMixin

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, user_data -- shorthand for connect_signal()
    function call for a single 'change' callback
 
This function will append the new radio button to group.
"first True" will set to True if group is empty.
 
Signals supported: 'change'
Register signal handler with:
  connect_signal(radio_button, 'change', callback [,user_data])
where callback is callback(radio_button, new_state [,user_data])
Unregister signal handlers with:
  disconnect_signal(radio_button, 'change', callback [,user_data])
 
>>> bgroup = [] # button group
>>> b1 = RadioButton(bgroup, u"Agree")
>>> b2 = RadioButton(bgroup, u"Disagree")
>>> len(bgroup)
2
>>> b1
<RadioButton selectable widget 'Agree' state=True>
>>> b2
<RadioButton selectable widget 'Disagree' state=False>
>>> b2.render((15,), focus=True).text # ... = b in Python 3
[...'( ) Disagree   ']

set_state(self, state, do_callback=True)

Set the RadioButton state.
 
state -- True, False or "mixed"
do_callback -- False to supress signal from this change
 
If state is True all other radio buttons in the same button
group will be set to False.
 
>>> bgroup = [] # button group
>>> b1 = RadioButton(bgroup, u"Agree")
>>> b2 = RadioButton(bgroup, u"Disagree")
>>> b3 = RadioButton(bgroup, u"Unsure")
>>> b1.state, b2.state, b3.state
(True, False, False)
>>> b2.set_state(True)
>>> b1.state, b2.state, b3.state
(False, True, False)
>>> def relabel_button(radio_button, new_state):
...     radio_button.set_label(u"Think Harder!")
>>> connect_signal(b3, 'change', relabel_button)
>>> b3
<RadioButton selectable widget 'Unsure' state=False>
>>> b3.set_state(True) # this will trigger the callback
>>> b3
<RadioButton selectable widget 'Think Harder!' state=True>

toggle_state(self)

Set state to True.
 
>>> bgroup = [] # button group
>>> b1 = RadioButton(bgroup, "Agree")
>>> b2 = RadioButton(bgroup, "Disagree")
>>> b1.state, b2.state
(True, False)
>>> b2.toggle_state()
>>> b1.state, b2.state
(False, True)
>>> b2.toggle_state()
>>> b1.state, b2.state
(False, True)

reserve_columns = 4

states = {False: <SelectableIcon selectable flow widget b'( )'>, True: <SelectableIcon selectable flow widget b'(X)'>, 'mixed': <SelectableIcon selectable flow widget b'(#)'>}

get_label(self)

Return label text.
 
>>> cb = CheckBox(u"Seriously")
>>> print cb.get_label()
Seriously
>>> print cb.label  # Urwid 0.9.9 or later
Seriously
>>> cb.set_label([('bright_attr', u"flashy"), u" normal"])
>>> print cb.label  #  only text is returned
flashy normal

get_state(self)

Return the state of the checkbox.

keypress(self, size, key)

Toggle state on 'activate' command.  
 
>>> assert CheckBox._command_map[' '] == 'activate'
>>> assert CheckBox._command_map['enter'] == 'activate'
>>> size = (10,)
>>> cb = CheckBox('press me')
>>> cb.state
False
>>> cb.keypress(size, ' ')
>>> cb.state
True
>>> cb.keypress(size, ' ')
>>> cb.state
False

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

Toggle state on button 1 press.
 
>>> size = (20,)
>>> cb = CheckBox("clickme")
>>> cb.state
False
>>> cb.mouse_event(size, 'mouse press', 1, 2, 0, True)
True
>>> cb.state
True

set_label(self, label)

Change the check box label.
 
label -- markup for label.  See Text widget for description
of text markup.
 
>>> cb = CheckBox(u"foo")
>>> cb
<CheckBox selectable widget 'foo' state=False>
>>> cb.set_label(('bright_attr', u"bar"))
>>> cb
<CheckBox selectable widget 'bar' state=False>

label

Return label text.
 
>>> cb = CheckBox(u"Seriously")
>>> print cb.get_label()
Seriously
>>> print cb.label  # Urwid 0.9.9 or later
Seriously
>>> cb.set_label([('bright_attr', u"flashy"), u" normal"])
>>> print cb.label  #  only text is returned
flashy normal

state

Return the state of the checkbox.

signals = ['change']

w

render(self, size, focus=False)

get_cursor_coords

get_pref_col

move_cursor_to_coords

pack

rows

selectable

sizing

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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, size, 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, size)

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(self, size, focus=False)

Render BarGraph.

selectable(self)

Return False.

set_bar_width(self, width)

Set a preferred bar width for calculate_bar_widths to use.
 
width -- width of bar or None for automatic width adjustment

set_data(self, bardata, top, hlines=None)

Store bar data, bargraph top and horizontal line positions.
 
bardata -- a list of bar values.
top -- maximum value for segments within bardata
hlines -- None or a bar value marking horizontal line positions
 
bar values are [ segment1, segment2, ... ] lists where top is 
the maximal value corresponding to the top of the bar graph and
segment1, segment2, ... are the values for the top of each 
segment of this bar.  Simple bar graphs will only have one
segment in each bar value.
 
Eg: if top is 100 and there is a bar value of [ 80, 30 ] then
the top of this bar will be at 80% of full height of the graph
and it will have a second segment that starts at 30%.

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

attlist -- list containing attribute or (attribute, character)
    tuple for background, first segment, and optionally
    following segments. ie. len(attlist) == num segments+1
    character defaults to ' ' if not specified.
hatt -- list containing attributes for horizontal lines. First 
    lement is for lines on background, second is for lines
           on first segment, third is for lines on second segment
    etc..
satt -- dictionary containing attributes for smoothed 
    transitions of bars in UTF-8 display mode. The values
    are in the form:
        (fg,bg) : attr
    fg and bg are integers where 0 is the graph background,
    1 is the first segment, 2 is the second, ...  
    fg > bg in all values.  attr is an attribute with a 
    foreground corresponding to fg and a background 
    corresponding to bg.
    
If satt is not None and the bar graph is being displayed in
a terminal using the UTF-8 encoding then the character cell
that is shared between the segments specified will be smoothed
with using the UTF-8 vertical eighth characters.
 
eg: set_segment_attributes( ['no', ('unsure',"?"), 'yes'] )
will use the attribute 'no' for the background (the area from
the top of the graph to the top of the bar), question marks 
with the attribute 'unsure' will be used for the topmost 
segment of the bar, and the attribute 'yes' will be used for
the bottom segment of the bar.

smooth_display(self, disp)

smooth (col, row*8) display into (col, row) display using
UTF vertical eighth characters represented as bar_type
tuple values:
( fg, bg, 1-7 )
where fg is the lower segment, bg is the upper segment and
1-7 is the vertical eighth character to use.

use_smoothed(self)

get_data

__metaclass__ = <class 'urwid.graphics.BarGraphMeta'>

Detect subclass get_data() method and dynamic change to
get_data() method and disable caching in these cases.
 
This is for backwards compatibility only, new programs
should use set_data() instead of overriding get_data().

eighths = u' \u2581\u2582\u2583\u2584\u2585\u2586\u2587'

hlines = u'_\u23ba\u23bb\u2500\u23bc\u23bd'

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

function GraphVScale [back to top]

class GraphVScale(BoxWidget) [back to top]

Method resolution order:

GraphVScale

BoxWidget

Widget

object

__init__(self, labels, top)

GraphVScale( [(label1 position, label1 markup),...], top )
label position -- 0 < position < top for the y position
label markup -- text markup for this label
top -- top y position
 
This widget is a vertical scale for the BarGraph widget that
can correspond to the BarGraph's horizontal lines

render(self, size, focus=False)

Render GraphVScale.

selectable(self)

Return False.

set_scale(self, labels, top)

set_scale( [(label1 position, label1 markup),...], top )
label position -- 0 < position < top for the y position
label markup -- text markup for this label
top -- top y position

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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 ProgressBar [back to top]

class ProgressBar(FlowWidget) [back to top]

Method resolution order:

ProgressBar

FlowWidget

Widget

object

__init__(self, normal, complete, current=0, done=100, satt=None)

normal -- attribute for uncomplete part of progress bar
complete -- attribute for complete part of progress bar
current -- current progress
done -- progress amount at 100%
satt -- attribute for smoothed part of bar where the foreground
    of satt corresponds to the normal part and the
    background corresponds to the complete part.  If satt
    is None then no smoothing will be done.

get_text(self)

Return the progress bar percentage text.

render(self, size, focus=False)

Render the progress bar.

rows(self, size, focus=False)

set_completion(self, current)

current -- current progress

current

done

eighths = u' \u258f\u258e\u258d\u258c\u258b\u258a\u2589'

text_align = 'center'

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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 PopUpLauncher [back to top]

class PopUpLauncher(DelegateToWidgetMixin, WidgetDecoration) [back to top]

Method resolution order:

PopUpLauncher

DelegateToWidgetMixin

WidgetDecoration

Widget

object

__init__(self, original_widget)

close_pop_up(self)

create_pop_up(self)

Subclass must override this method and have is return a widget
to be used for the pop-up.  This method is called once each time
the pop-up is opened.

get_pop_up_parameters(self)

Subclass must override this method and have it return a dict, eg:
 
{'left':0, 'top':1, 'overlay_width':30, 'overlay_height':4}
 
This method is called each time this widget is rendered.

open_pop_up(self)

render(self, size, focus=False)

get_cursor_coords

get_pref_col

keypress

mouse_event

move_cursor_to_coords

pack

rows

selectable

sizing

base_widget

Return the widget without decorations.  If there is only one
Decoration then this is the same as original_widget.
 
>>> t = Text('hello')
>>> wd1 = WidgetDecoration(t)
>>> wd2 = WidgetDecoration(wd1)
>>> wd3 = WidgetDecoration(wd2)
>>> wd3.original_widget is wd2
True
>>> wd3.base_widget is t
True

original_widget

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

__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 PopUpTarget [back to top]

class PopUpTarget(WidgetDecoration) [back to top]

Method resolution order:

PopUpTarget

WidgetDecoration

Widget

object

__init__(self, original_widget)

get_cursor_coords(self, size)

get_pref_col(self, size)

keypress(self, size, key)

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

move_cursor_to_coords(self, size, x, y)

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

render(self, size, focus=False)

selectable(self)

sizing(self)

base_widget

Return the widget without decorations.  If there is only one
Decoration then this is the same as original_widget.
 
>>> t = Text('hello')
>>> wd1 = WidgetDecoration(t)
>>> wd2 = WidgetDecoration(wd1)
>>> wd3 = WidgetDecoration(wd2)
>>> wd3.original_widget is wd2
True
>>> wd3.base_widget is t
True

original_widget

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

__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 BigText [back to top]

class BigText(FixedWidget) [back to top]

Method resolution order:

BigText

FixedWidget

Widget

object

__init__(self, markup, font)

markup -- same as Text widget markup
font -- instance of a Font class

get_text(self)

Returns (text, attributes).

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

render(self, size, focus=False)

set_font(self, font)

set_text(self, markup)

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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 get_all_fonts [back to top]

get_all_fonts()

Return a list of (font name, font class) tuples.

Build custom widgets

function WidgetWrap [back to top]

class WidgetWrap(DelegateToWidgetMixin, Widget) [back to top]

Method resolution order:

WidgetWrap

DelegateToWidgetMixin

Widget

object

__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.
 
The purpose of this widget is to provide a base class for
widgets that compose other widgets for their display and
behaviour.  The details of that composition should not affect
users of the subclass.  The subclass may decide to expose some
of the wrapped widgets by behaving like a ContainerWidget or
WidgetDecoration, or it may hide them from outside access.

w

render(self, size, focus=False)

get_cursor_coords

get_pref_col

keypress

mouse_event

move_cursor_to_coords

pack

rows

selectable

sizing

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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 WidgetDecoration [back to top]

class WidgetDecoration(Widget) [back to top]

Method resolution order:

WidgetDecoration

Widget

object

__init__(self, original_widget)

original_widget -- the widget being decorated
 
This is a base class for decoration widgets, widgets
that contain one or more widgets and only ever have
a single focus.  This type of widget will affect the
display or behaviour of the original_widget but it is
not part of determining a chain of focus.
 
Don't actually do this -- use a WidgetDecoration subclass
instead, these are not real widgets:
>>> WidgetDecoration(Text(u"hi"))
<WidgetDecoration flow widget <Text flow widget 'hi'>>

selectable(self)

sizing(self)

base_widget

Return the widget without decorations.  If there is only one
Decoration then this is the same as original_widget.
 
>>> t = Text('hello')
>>> wd1 = WidgetDecoration(t)
>>> wd2 = WidgetDecoration(wd1)
>>> wd3 = WidgetDecoration(wd2)
>>> wd3.original_widget is wd2
True
>>> wd3.base_widget is t
True

original_widget

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

__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 WidgetPlaceholder [back to top]

class WidgetPlaceholder(DelegateToWidgetMixin, WidgetDecoration) [back to top]

Method resolution order:

WidgetPlaceholder

DelegateToWidgetMixin

WidgetDecoration

Widget

object

render(self, size, focus=False)

get_cursor_coords

get_pref_col

keypress

mouse_event

move_cursor_to_coords

pack

rows

selectable

sizing

__init__(self, original_widget)

original_widget -- the widget being decorated
 
This is a base class for decoration widgets, widgets
that contain one or more widgets and only ever have
a single focus.  This type of widget will affect the
display or behaviour of the original_widget but it is
not part of determining a chain of focus.
 
Don't actually do this -- use a WidgetDecoration subclass
instead, these are not real widgets:
>>> WidgetDecoration(Text(u"hi"))
<WidgetDecoration flow widget <Text flow widget 'hi'>>

base_widget

Return the widget without decorations.  If there is only one
Decoration then this is the same as original_widget.
 
>>> t = Text('hello')
>>> wd1 = WidgetDecoration(t)
>>> wd2 = WidgetDecoration(wd1)
>>> wd3 = WidgetDecoration(wd2)
>>> wd3.original_widget is wd2
True
>>> wd3.base_widget is t
True

original_widget

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

__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.

Abstract widgets & interfaces

Widget interface definition [back to top]

get_cursor_coords(self, size)

size -- flow widgets: (maxcol,)  box widgets: (maxcol,maxrow)
        where maxcol and maxrow are the maximum screen columns
    and rows for the widget when rendered
    
Returns (col,row) coordinates for cursor or None if no cursor.
 
MUST be implemented if render function returns a canvas with
a cursor.  
MUST match the cursor in the canvas returned by render function
when focus=True.
Caller MUST treat no implementation as equivalent to an 
implementation that always returns None.

get_pref_col(self, size)

size -- flow widgets: (maxcol,)  box widgets: (maxcol,maxrow)
        where maxcol and maxrow are the maximum screen columns
    and rows for the widget when rendered
    
Returns the preferred screen column as an integer or None.
 
Caller MUST treat no implementation as equivalent to an 
implementation that always returns None.

keypress(self, size, key)

size -- flow widgets: (maxcol,)  box widgets: (maxcol,maxrow)
        where maxcol and maxrow are the maximum screen columns
    and rows for the widget when rendered
key -- key pressed
 
Returns None if key was handled, returns key if not handled.
 
MUST be implemented if selectable function returns True.
MUST NOT be called if selectable function returns False.

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

size -- flow widgets: (maxcol,)  box widgets: (maxcol,maxrow)
        where maxcol and maxrow are the maximum screen columns
    and rows for the widget when rendered
event -- event part of mouse event structure, eg. 'press',
         'release', 'drag', 'meta press' etc..
button -- button number for event between 1 and 5, may be 0
          on button release events if button is unknown
col -- screen column of event, relative to left edge of widget
row -- screen row of event, relative to top edge of widget
focus -- True if this widget is in focus
 
Returns True if event was handled, False otherwise.
 
Caller MUST treat no implementation as equivalent to an
implementation that always returns False.

move_cursor_to_coords(self, size, col, row)

size -- flow widgets: (maxcol,)  box widgets: (maxcol,maxrow)
        where maxcol and maxrow are the maximum screen columns
    and rows for the widget when rendered
col -- desired screen column for cursor to appear, relative
       to left edge of widget
row -- desired screen row for cursor to appear, relative to
       top edge of widget
    
Returns True on success, False on failure.
 
MUST succeed if there is any column on passed row that the
cursor may be moved to.
Caller MUST treat no implementation as equivalent to an
implementation that always returns True.

render(self, size, focus=False)

size -- flow widgets: (maxcol,)  box widgets: (maxcol,maxrow)
        where maxcol and maxrow are the maximum screen columns
    and rows for the canvas returned
focus -- True if this widget is in focus
 
Returns a canvas object.
 
MUST be implemented.
MUST NOT return a canvas with a cursor when focus=False.

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

maxcol -- maximum screen columns for rendered widget
focus -- True if this widget is in focus
 
Returns an integer number or screen rows required.
 
MUST be implemented by all flow widgets.
MUST match the number of rows in the canvas returned by
render function called with the same parameters.

selectable(self)

Returns True if this widget will accept keyboard input and
should take the focus when changing focus between widgets.
 
MUST be implemented.

function BoxWidget [back to top]

class BoxWidget(Widget) [back to top]

Method resolution order:

BoxWidget

Widget

object

render(self, size, focus=False)

All widgets must implement this function.

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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 FlowWidget [back to top]

class FlowWidget(Widget) [back to top]

Method resolution order:

FlowWidget

Widget

object

render(self, size, focus=False)

All widgets must implement this function.

rows(self, size, focus=False)

All flow widgets must implement this function.

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

pack(self, size, focus=False)

Return a 'packed' (maxcol, maxrow) for this widget.  Default 
implementation (no packing defined) returns size, and
calculates maxrow if not given.

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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 FixedWidget [back to top]

class FixedWidget(Widget) [back to top]

Method resolution order:

FixedWidget

Widget

object

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

All fixed widgets must implement this function.

render(self, size, focus=False)

All widgets must implement this function.

__repr__ = split_repr(self)

Return a helpful description of the object using
_repr_words() and _repr_attrs() to add
to the description.  This function may be used by
adding code to your class like this:
 
>>> class Foo(object):
...     __repr__ = split_repr
...     def _repr_words(self):
...         return ["words", "here"]
...     def _repr_attrs(self):
...         return {'attrs': "appear too"}
>>> Foo()
<Foo words here attrs='appear too'>
>>> class Bar(Foo):
...     def _repr_words(self):
...         return Foo._repr_words(self) + ["too"]
...     def _repr_attrs(self):
...         return dict(Foo._repr_attrs(self), barttr=42)
>>> Bar()
<Bar words here too attrs='appear too' barttr=42>

selectable(self)

Return True if this widget should take focus.  Default
implementation returns the value of self._selectable.

sizing(self)

Return a set including one or more of 'box', 'flow' and
'fixed'.  Default implementation returns the value of
self._sizing.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

base_widget

__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.

ListBox list walkers

List Walker interface definition [back to top]

get_focus(self)

Returns (widget, position).
 
MUST be implemented.
Caller MUST NOT assume that position object may be stored and
reused after contents of list change.

get_next(self, position)

position -- a position returned by get_focus or get_next
 
Returns (widget below, position below).
 
MUST be implemented.
Caller MUST NOT assume that position object may be stored and
reused after contents of list change.

get_prev(self, position)

position -- a position returned by get_focus or get_prev
 
Returns (widget above, position above).
 
MUST be implemented.
Caller MUST NOT assume that position object may be stored and
reused after contents of list change.

set_focus(self, position)

position -- a position returned by get_focus, get_next or
            get_prev
 
Returns None.
 
MUST be implemented.  Should send "modified" signal (or call
self._modified if inheriting from ListWalker)

function ListWalker [back to top]

class ListWalker(object) [back to top]

__hash__(self)

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__metaclass__ = <class 'urwid.signals.MetaSignals'>

register the list of signals in the class varable signals,
including signals in superclasses.

signals = ['modified']

function SimpleListWalker [back to top]

class SimpleListWalker(MonitoredList, ListWalker) [back to top]

Method resolution order:

SimpleListWalker

MonitoredList

list

ListWalker

object

__hash__(self)

__init__(self, contents)

contents -- list to copy into this object
 
Changes made to this object (when it is treated as a list) are
detected automatically and will cause ListBox objects using
this list walker to be updated.

get_focus(self)

Return (focus widget, focus position).

get_next(self, start_from)

Return (widget after start_from, position after start_from).

get_prev(self, start_from)

Return (widget before start_from, position before start_from).

set_focus(self, position)

Set focus position.

set_modified_callback(self, callback)

This function inherited from MonitoredList is not 
implemented in SimleListWalker.
 
Use connect_signal(list_walker, "modified", ...) instead.

contents

Return self.
 
Provides compatibility with old SimpleListWalker class.

__add__ = call_modified_wrapper(self, *args, **kwargs)

__delitem__ = call_modified_wrapper(self, *args, **kwargs)

__delslice__ = call_modified_wrapper(self, *args, **kwargs)

__iadd__ = call_modified_wrapper(self, *args, **kwargs)

__imul__ = call_modified_wrapper(self, *args, **kwargs)

__repr__(self)

__rmul__ = call_modified_wrapper(self, *args, **kwargs)

__setitem__ = call_modified_wrapper(self, *args, **kwargs)

__setslice__ = call_modified_wrapper(self, *args, **kwargs)

append = call_modified_wrapper(self, *args, **kwargs)

extend = call_modified_wrapper(self, *args, **kwargs)

insert = call_modified_wrapper(self, *args, **kwargs)

pop = call_modified_wrapper(self, *args, **kwargs)

remove = call_modified_wrapper(self, *args, **kwargs)

reverse = call_modified_wrapper(self, *args, **kwargs)

sort = call_modified_wrapper(self, *args, **kwargs)

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

__contains__(...)

x.__contains__(y) <==> y in x

__eq__(...)

x.__eq__(y) <==> x==y

__ge__(...)

x.__ge__(y) <==> x>=y

__getattribute__(...)

x.__getattribute__('name') <==> x.name

__getitem__(...)

x.__getitem__(y) <==> x[y]

__getslice__(...)

x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.

__gt__(...)

x.__gt__(y) <==> x>y

__iter__(...)

x.__iter__() <==> iter(x)

__le__(...)

x.__le__(y) <==> x<=y

__len__(...)

x.__len__() <==> len(x)

__lt__(...)

x.__lt__(y) <==> x<y

__mul__(...)

x.__mul__(n) <==> x*n

__ne__(...)

x.__ne__(y) <==> x!=y

__reversed__(...)

L.__reversed__() -- return a reverse iterator over the list

__sizeof__(...)

L.__sizeof__() -- size of L in memory, in bytes

count(...)

L.count(value) -> integer -- return number of occurrences of value

index(...)

L.index(value, [start, [stop]]) -> integer -- return first index of value.
Raises ValueError if the value is not present.

__new__ = <built-in method __new__ of type object>

T.__new__(S, ...) -> a new object with type S, a subtype of T

__metaclass__ = <class 'urwid.signals.MetaSignals'>

register the list of signals in the class varable signals,
including signals in superclasses.

signals = ['modified']

function PollingListWalker [back to top]

class PollingListWalker(object) [back to top]

__init__(self, contents)

contents -- list to poll for changes

get_focus(self)

Return (focus widget, focus position).

get_next(self, start_from)

Return (widget after start_from, position after start_from).

get_prev(self, start_from)

Return (widget before start_from, position before start_from).

set_focus(self, position)

Set focus position.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

Dynamic tree views

function TreeWidget [back to top]

class TreeWidget(WidgetWrap) [back to top]

Method resolution order:

TreeWidget

WidgetWrap

DelegateToWidgetMixin

Widget

object

__init__(self, node)

first_child(self)

Return first child if expanded.

get_display_text(self)

get_indent_cols(self)

get_indented_widget(self)

get_inner_widget(self)

get_node(self)

keypress(self, size, key)

Handle expand & collapse requests (non-leaf nodes)

last_child(self)

Return last child if expanded.

load_inner_widget(self)

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

next_inorder(self)

Return the next TreeWidget depth first from this one.

prev_inorder(self)

Return the previous TreeWidget depth first from this one.

selectable(self)

Allow selection of non-leaf nodes so children may be (un)expanded

update_expanded_icon(self)

Update display widget text for parent widgets

expanded_icon = <SelectableIcon selectable flow widget b'-'>

indent_cols = 3

unexpanded_icon = <SelectableIcon selectable flow widget b'+'>

w

render(self, size, focus=False)

get_cursor_coords

get_pref_col

move_cursor_to_coords

pack

rows

sizing