Urwid Reference

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) 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' background -- background colour, one of: 'black', 'dark red', 'dark green', 'brown', 'dark blue', 'dark magenta', 'dark cyan', 'light gray' 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

Methods defined here:

keypress(self, (maxcol, maxrow), key): Return key. No keys are handled by default.

class Frame(BoxWidget)

Methods defined here:

__init__(self, body, header=None, footer=None): 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)

keypress(self, (maxcol, maxrow), key): Pass keypress to body widget.

render(self, (maxcol, maxrow), focus=False): Render frame and return it.

class ListBox(BoxWidget)

Methods defined here:

__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

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.

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.

class SimpleListWalker

Methods defined here:

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

Content widgets

class FlowWidget

Methods defined here:

keypress(self, (maxcol,), key): Return key. No keys are handled by default.

selectable(self): Return False. Not selectable by default.

class Text(FlowWidget)

Methods defined here:

__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

Data and other attributes defined here:

align_mode = 'left'

wrap_mode = 'space'

Methods inherited from FlowWidget:

keypress(self, (maxcol,), key): Return key. No keys are handled by default.

selectable(self): Return False. Not selectable by default.

class Edit(Text)

Method resolution order:: Edit; Text; FlowWidget

Methods defined here:

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

get_cursor_coords(self, (maxcol,)): Return the (x,y) coordinates of cursor within widget.

get_pref_col(self, (maxcol,)): Return the preferred column for the cursor, or None.

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

Methods inherited from Text:

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

Data and other attributes inherited from Text:

align_mode = 'left'

wrap_mode = 'space'

class IntEdit(Edit)

Method resolution order:: IntEdit; Edit; Text; FlowWidget

Methods defined here:

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

Methods inherited from Edit:

get_cursor_coords(self, (maxcol,)): Return the (x,y) coordinates of cursor within widget.

get_pref_col(self, (maxcol,)): Return the preferred column for the cursor, or None.

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

Methods inherited from Text:

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

Data and other attributes inherited from Text:

align_mode = 'left'

wrap_mode = 'space'

Composite widgets

class Columns

Methods defined here:

__init__(self, widget_list, dividechars=0): widget_list -- list of flow widgets or list of box widgets dividechars -- blank characters between columns

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

get_focus_column(self): Return the focus column index.

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.

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_column(self, num): Set the column in focus by its index in self.widget_list.

class Pile(FlowWidget)

Methods defined here:

__init__(self, widget_list): widget_list -- list of flow widgets

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.

Methods inherited from FlowWidget:

keypress(self, (maxcol,), key): Return key. No keys are handled by default.

selectable(self): Return False. Not selectable by default.

Decorations

class AttrWrap

Methods defined here:

__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 Copy w.get_cursor_coords, w.move_cursor_to_coords, w.get_pref_col functions to this widget if they exist.

keypress(self, maxvals, key): Pass keypress to self.w.

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.

rows(self, (maxcol,), focus=False): Return the rows needed for self.w.

selectable(self): Return the selectable value of self.w.

class Divider(FlowWidget)

Methods defined here:

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

Methods inherited from FlowWidget:

keypress(self, (maxcol,), key): Return key. No keys are handled by default.

selectable(self): Return False. Not selectable by default.

Canvas painting

canvas.Canvas = class Canvas

Methods defined here:

__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

canvas.CanvasCombine = CanvasCombine(l): Stack canvases in l vertically and return resulting canvas.

canvas.CanvasJoin = 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

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)

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"

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

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"] ] )

html_fragment.screenshot_collect = screenshot_collect(): Return screenshots as a list of HTML fragments.

html_fragment.HtmlGenerator = class HtmlGenerator

Methods defined here:

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

Data and other attributes defined here:

fragments = []

keys = []

sizes = []