Urwid Reference

Urwid class interfaces

Widget interface definition [back to top]

get_cursor_coords(self, size)

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)

Returns integer preferred column or None.
 
Caller MUST treat no implementation as equivalent to an 
implementation that always returns None.

keypress(self, size, key)

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.

move_cursor_to_coords(self, size, col, row)

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)

Returns a canvas object.
 
MUST be implemented.
MUST NOT return a canvas with a cursor when focus=False.

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

Returns an integer number or rows.
 
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 or False.
 
MUST be implemented.

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)

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)

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)

Returns None.
 
MUST be implemented.

User interface wrapper

curses_display.Screen [back to top]

__init__(self)

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

Paint screen with rendered canvas.

get_cols_rows(self)

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

get_input(self, raw_keys=False)

Return pending input as a list.
 
raw_keys -- return raw keycodes as well as translated versions
 
This function will immediately return all the input since the
last time it was called.  If there is no input pending it will
wait briefly for new input.
 
If raw_keys is False (default) this function will return a list
of keys pressed.  If raw_keys is True this function will return
a ( keys pressed, raw keycodes ) tuple instead.
 
Examples of keys returned
-------------------------
ASCII printable characters:  " ", "a", "0", "A", "-", "/" 
ASCII control characters:  "tab", "enter"
Escape sequences:  "up", "page up", "home", "insert", "f1"
Key combinations:  "shift f1", "meta a", "ctrl b"
Window events:  "window resize"
 
When double-byte encoding is not enabled
"Extended ASCII" characters:  "\xa1", "\xb2", "\xfe"
 
When double-byte encoding is enabled
Double-byte characters:  "\xa1\xea", "\xb2\xd4"

register_palette(self, l)

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

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

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

run_wrapper(self, fn)

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

Top-level widgets

class BoxWidget [back to top]

selectable(self)

Return True.  Selectable by default.

class Frame(BoxWidget) [back to top]

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

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

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

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

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

Pass keypress to widget in focus.

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

Render frame and return it.

set_focus(self, part)

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

selectable(self)

Return True.  Selectable by default.

class Filler(BoxWidget) [back to top]

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

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

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

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

get_cursor_coords(self, (maxcol, maxrow))

Return cursor coords from self.body if any.

get_pref_col(self, (maxcol, maxrow))

Return pref_col from self.body if any.

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

Pass keypress to self.body.

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

Pass to self.body.

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

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

selectable(self)

Return selectable from body.

class ListBox(BoxWidget) [back to top]

__init__(self, body)

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

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

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

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

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

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

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

get_focus(self)

Return a (focus widget, focus position) tuple.

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

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

render(self, (maxcol, maxrow), 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.

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

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

update_pref_col_from_focus(self, (maxcol, maxrow))

Update self.pref_col from the focus widget.

selectable(self)

Return True.  Selectable by default.

class SimpleListWalker [back to top]

__init__(self, contents)

contents -- list to walk

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.

Decorations

class AttrWrap [back to top]

__getattr__(self, name)

Call getattr on wrapped widget.

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

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

render(self, size, focus=False)

Render self.w and apply attribute. Return canvas.
 
size -- (maxcol,) if self.w contains a flow widget or
        (maxcol, maxrow) if it contains a box widget.

class Padding [back to top]

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

w -- a box or flow widget to pad on the left and/or right
align -- one of:
    'left', 'center', 'right'
    ('fixed left', columns)
    ('fixed right', columns)
    ('relative', percentage 0=left 100=right)
width -- one of:
    number of columns wide 
    ('fixed right', columns)  Only if align is 'fixed left'
    ('fixed left', columns)  Only if align is 'fixed right'
    ('relative', percentage of total width)    
min_width -- the minimum number of columns for the widget
    when width is not fixed
 
Padding widgets will try to satisfy width argument first by
reducing the align amount when necessary.  If width still 
cannot be satisfied it will also be reduced.

get_cursor_coords(self, size)

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

get_pref_col(self, size)

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

keypress(self, size, key)

Pass keypress to self.w.

move_cursor_to_coords(self, size, x, y)

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

padding_values(self, size)

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

Return the rows needed for self.w.

selectable(self)

Return the selectable value of self.w.

class Divider(FlowWidget) [back to top]

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

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

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

Render the divider as a canvas and return it.

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

Return the number of lines that will be rendered.

selectable(self)

Return False.  Not selectable by default.

Content widgets

class FlowWidget [back to top]

selectable(self)

Return False.  Not selectable by default.

class Text(FlowWidget) [back to top]

__init__(self, markup, align=None, wrap=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 or None (widget will use Text.align_mode)
wrap -- wrap mode or None (widget will use Text.wrap_mode)

get_line_translation(self, maxcol)

Return line translation for mapping self.text to a canvas.
 
The line translation is a list of (l_pad, l_trim, r_trim, epos) 
tuples. Each tuple in the line translation represents one row.
l_pad -- number of spaces to add on the left of the line
l_trim -- number of characters to remove from left of line
r_trim -- number of characters to remove from right of line
epos -- character index at the end of the line (start of next)

get_text(self)

get_text() -> text, attributes
 
text -- complete string content of text widget
attributes -- run length encoded attributes for text

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

Render contents with wrapping and alignment.  Return canvas.

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

Return the number of rows the rendered text spans.

set_align_mode(self, mode)

Set text alignment / justification.  Valid modes include:
        'left', 'center', 'right'

set_text(self, markup)

Set content of text widget.

set_wrap_mode(self, mode)

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

align_mode = 'left'

wrap_mode = 'space'

selectable(self)

Return False.  Not selectable by default.

class Edit(Text) [back to top]

Method resolution order:

Edit

Text

FlowWidget

__init__(self, caption='', edit_text='', multiline=False, align=None, wrap=None, allow_tab=False, edit_pos=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

get_cursor_coords(self, (maxcol,))

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

get_edit_text(self)

Return the edit text for this widget.

get_pref_col(self, (maxcol,))

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

get_text(self)

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

insert_text(self, text)

Insert text at the cursor position and update cursor.

keypress(self, (maxcol,), key)

Handle editing keystrokes, return others.

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

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

position_coords(self, maxcol, pos)

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

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

Render edit widget and return canvas.  Include cursor when in
focus.

selectable(self)

set_caption(self, caption)

Set the caption markup for this widget.

set_edit_pos(self, pos)

Set the cursor position with a self.edit_text offset.

set_edit_text(self, text)

Set the edit text for this widget.

update_text(self)

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

valid_char(self, ch)

Return true for printable characters.

within_double_byte(self, maxcol, pos)

Return whether pos is on a double-byte character.
 
Return values:
0 -- not within or double byte encoding not enabled
1 -- on the 1st half
2 -- on the 2nd half

get_line_translation(self, maxcol)

Return line translation for mapping self.text to a canvas.
 
The line translation is a list of (l_pad, l_trim, r_trim, epos) 
tuples. Each tuple in the line translation represents one row.
l_pad -- number of spaces to add on the left of the line
l_trim -- number of characters to remove from left of line
r_trim -- number of characters to remove from right of line
epos -- character index at the end of the line (start of next)

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

Return the number of rows the rendered text spans.

set_align_mode(self, mode)

Set text alignment / justification.  Valid modes include:
        'left', 'center', 'right'

set_text(self, markup)

Set content of text widget.

set_wrap_mode(self, mode)

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

align_mode = 'left'

wrap_mode = 'space'

class IntEdit(Edit) [back to top]

Method resolution order:

IntEdit

Edit

Text

FlowWidget

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

caption -- caption markup
default -- default edit value

keypress(self, (maxcol,), key)

Handle editing keystrokes.  Return others.

valid_char(self, ch)

Return true for decimal digits.

value(self)

Return the numeric value of self.edit_text.

get_cursor_coords(self, (maxcol,))

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

get_edit_text(self)

Return the edit text for this widget.

get_pref_col(self, (maxcol,))

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

get_text(self)

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

insert_text(self, text)

Insert text at the cursor position and update cursor.

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

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

position_coords(self, maxcol, pos)

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

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

Render edit widget and return canvas.  Include cursor when in
focus.

selectable(self)

set_caption(self, caption)

Set the caption markup for this widget.

set_edit_pos(self, pos)

Set the cursor position with a self.edit_text offset.

set_edit_text(self, text)

Set the edit text for this widget.

update_text(self)

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

within_double_byte(self, maxcol, pos)

Return whether pos is on a double-byte character.
 
Return values:
0 -- not within or double byte encoding not enabled
1 -- on the 1st half
2 -- on the 2nd half

get_line_translation(self, maxcol)

Return line translation for mapping self.text to a canvas.
 
The line translation is a list of (l_pad, l_trim, r_trim, epos) 
tuples. Each tuple in the line translation represents one row.
l_pad -- number of spaces to add on the left of the line
l_trim -- number of characters to remove from left of line
r_trim -- number of characters to remove from right of line
epos -- character index at the end of the line (start of next)

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

Return the number of rows the rendered text spans.

set_align_mode(self, mode)

Set text alignment / justification.  Valid modes include:
        'left', 'center', 'right'

set_text(self, markup)

Set content of text widget.

set_wrap_mode(self, mode)

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

align_mode = 'left'

wrap_mode = 'space'

class Button(FlowWidget) [back to top]

__init__(self, label, on_press)

label -- markup for button label
on_press -- callback function for button "press"
           on_press( button object )

get_cursor_coords(self, (maxcol,))

Return the location of the cursor.

get_label(self)

keypress(self, (maxcol,), key)

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

Display button. Show a cursor when in focus.

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

Return rows required for button.

selectable(self)

set_label(self, label)

button_left = <urwid.widget.Text instance>

button_right = <urwid.widget.Text instance>

class CheckBox(FlowWidget) [back to top]

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

label -- markup for check box label
state -- False, True or "mixed"
has_mixed -- True if "mixed" is a state to cycle through
on_state_change -- callback function for state changes
                   on_state_change( check box, new state )

get_cursor_coords(self, (maxcol,))

Return cursor coords from display widget.

get_label(self)

Return label text.

get_state(self)

Return the state of the checkbox.

keypress(self, (maxcol,), key)

Toggle state on space or enter.

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

Render check box.

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

Return rows required for check box.

selectable(self)

set_label(self, label)

Change the check box label.

set_state(self, state)

Call on_state_change then change the check box state.

reserve_columns = 4

states = {False: <urwid.widget.SelectableIcon instance>, True: <urwid.widget.SelectableIcon instance>, 'mixed': <urwid.widget.SelectableIcon instance>}

class RadioButton(FlowWidget) [back to top]

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

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

get_cursor_coords(self, (maxcol,))

Return cursor coords from display widget.

get_label(self)

Return label text.

get_state(self)

Return the state of the radio button.

keypress(self, (maxcol,), key)

Set state to True on space or enter.

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

Render radio button.

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

Return rows required for radio button.

selectable(self)

set_label(self, label)

Change the check box label.

set_state(self, state)

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

reserve_columns = 4

states = {False: <urwid.widget.SelectableIcon instance>, True: <urwid.widget.SelectableIcon instance>, 'mixed': <urwid.widget.SelectableIcon instance>}

Composite widgets

class Columns [back to top]

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

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
min_width -- minimum width for each column before it is hidden
 
widget_list may also contain tuples such as:
('fixed', width, widget) give this column a fixed width
('weight', weight, widget) give this column a relative weight
 
widgets not in a tuple are the same as ('weight', 1, widget)

column_widths(self, size)

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

get_cursor_coords(self, size)

Return the cursor coordinates from the focus widget.

get_focus(self)

Return the widget in focus.

get_focus_column(self)

Return the focus column index.

get_pref_col(self, size)

Return the pref col from the column in focus.

keypress(self, size, key)

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

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, (maxcol,), focus=0)

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

Set the column in focus with a widget in self.widget_list.

set_focus_column(self, num)

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

class Pile(FlowWidget) [back to top]

__init__(self, widget_list, focus_item=0)

widget_list -- list of flow widgets
focus_item -- widget or integer index

get_cursor_coords(self, (maxcol,))

Return the cursor coordinates of the focus widget.

get_focus(self)

Return the widget in focus.

get_pref_col(self, (maxcol,))

Return the preferred column for the cursor, or None.

keypress(self, (maxcol,), key)

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

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

Capture pref col and set new focus.

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

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

rows(self, (maxcol,), 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

class GridFlow(FlowWidget) [back to top]

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

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

generate_display_widget(self, (maxcol,))

Actually generate display widget (ignoring cache)

get_cursor_coords(self, (maxcol,))

Get cursor from display widget.

get_display_widget(self, (maxcol,))

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

get_pref_col(self, (maxcol,))

Return pref col from display widget.

keypress(self, (maxcol,), key)

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

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

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

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

Use display widget to render.

rows(self, (maxcol,), 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

Canvas painting

class Canvas [back to top]

__init__(self, text=None, attr=None, cursor=None)

text -- list of strings, one for each line
attr -- list of run length encoded attributes for text
cursor -- (x,y) of cursor or None

rows(self)

Return the number of rows in this canvas.

translate_coords(self, dx, dy)

Shift cursor coords by (dx, dy).

trim(self, top, count=None)

Trim lines from the top and/or bottom of canvas.
 
top -- number of lines to remove from top
count -- number of lines to keep, or None for all the rest

trim_end(self, end)

Trim lines from the bottom of the canvas.
 
end -- number of lines to remove from the end

function CanvasCombine [back to top]

CanvasCombine(l)

Stack canvases in l vertically and return resulting canvas.

function CanvasJoin [back to top]

CanvasJoin(l)

Join canvases in l horizontally. Return result.
 
l -- [canvas1, colnum2, canvas2, ... ,colnumN, canvasN]
        colnumX is the column number to start for canvasX

Custom formatting rules

function util.register_align_mode [back to top]

util.register_align_mode = register_align_mode(x, fn)

Register custom align mode x function fn.
 
Custom alignment function:
fn( text, width, b, wrap_mode, align_mode )
        text -- original text string to align
        b -- line breaks calculated from wrap_mode function
        wrap_mode -- current wrap_mode
        align_mode -- current align_mode
Must return:
line translation (see Text.get_line_translation for description)

function util.register_wrap_mode [back to top]

util.register_wrap_mode = register_wrap_mode(x, fn)

Register custom wrap mode x function fn.
 
Custom wrapping function:
fn( text, width, wrap_mode )
        text -- original text string to wrap
        width -- max number of characters per row
        wrap_mode -- current wrap_mode
Must return:
list of offsets into text for line breaks
 
eg. [4,6] would split "hallabaloo" into "hall","ab","aloo"

function util.set_double_byte_encoding [back to top]

util.set_double_byte_encoding = set_double_byte_encoding(dbe)

Enable/disable special processing for double-byte characters.
 
dbe -- True to enable, False to disable.

Screen capture

function html_fragment.screenshot_init [back to top]

html_fragment.screenshot_init = screenshot_init(sizes, keys)

Replace curses_display.Screen class with HtmlGenerator.
 
Call this function before executing an application that uses 
curses_display.Screen to have that code use HtmlGenerator instead.
 
sizes -- list of ( columns, rows ) tuples to be returned by each call
         to HtmlGenerator.get_cols_rows()
keys -- list of lists of keys to be returned by each call to
        HtmlGenerator.get_input()
 
Lists of keys may include "window resize" to force the application to
call get_cols_rows and read a new screen size.
 
For example, the following call will prepare an application to:
 1. start in 80x25 with its first call to get_cols_rows()
 2. take a screenshot when it calls draw_screen(..)
 3. simulate 5 "down" keys from get_input()
 4. take a screenshot when it calls draw_screen(..)
 5. simulate keys "a", "b", "c" and a "window resize"
 6. resize to 20x10 on its second call to get_cols_rows()
 7. take a screenshot when it calls draw_screen(..)
 8. simulate a "Q" keypress to quit the application
 
screenshot_init( [ (80,25), (20,10) ],
        [ ["down"]*5, ["a","b","c","window resize"], ["Q"] ] )

function html_fragment.screenshot_collect [back to top]

html_fragment.screenshot_collect = screenshot_collect()

Return screenshots as a list of HTML fragments.

html_fragment.HtmlGenerator [back to top]

__init__(self)

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

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

get_cols_rows(self)

Return the next screen size in HtmlGenerator.sizes.

get_input(self)

Return the next list of keypresses in HtmlGenerator.keys.

register_palette(self, l)

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

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

Register a single palette entry.
 
name -- new entry/attribute name
foreground -- foreground colour
background -- background colour
mono -- monochrome terminal attribute
 
See curses_display.register_palette_entry for more info.

run_wrapper(self, fn)

Call fn.

fragments = []

keys = []

sizes = []