Containers

Containers are structures to hold widgets and handle automatic positioning. Containers are essentially widgets containing other widgets. Below is a collection of default containers which can position widgets, but they can do more (e.g. handle user input). Recursive composition of containers is supported.

Customized containers can also be created. See the Creating a custom container section.

Container classes

class simpleline.render.containers.ListRowContainer(columns, items=None, columns_width=None, spacing=3, numbering=True)

Bases: simpleline.render.containers.Container

Place widgets in rows automatically.

Compared to the ColumnWidget this is able to handle word wrapping correctly.

There is numbering N) automatically for all items. To disable this feature call self.key_pattern = None. If you want other numbering then look on KeyPattern class.

Widgets will be placed based on the number of columns in the following way:

1) w1 2) w2 3) w3 4) w4 5) w5 6) w6 ….

add(item, callback=None, data=None)

Add item to the Container.

Parameters:
  • item (Could be item (based on simpleline.render.widgets.Widget) or other container (based on simpleline.render.containers.Container).) – Add item to this container.
  • callback (function func(data).) – Add callback for this item. This callback will be called when user activate this item.
  • data – Data which will be passed to the callback.
  • data – Anything.
Returns:

ID of the item in this Container.
Return type:

int
clear()

Clears this widgets buffer and resets cursor.

content

Return a list (rows) of lists (columns) with one character elements.

create_number_label(item_id)

Create TextWidget from KeyPattern.

Parameters:item_id (int) – Create label for item with this id.
Returns:Widget with label for the item with item_id.
Return type:simpleline.render.widgets.TextWidget instance.
draw(w, row=None, col=None, block=False)

Copy w widget’s content to this widget’s buffer at row, col position.

Parameters:
  • w (class Widget) – widget to take content from
  • row (int) – row number to start at (default is at the cursor position)
  • col (int) – column number to start at (default is at the cursor position)
  • block (boolean) – when printing newline, start at column col (True) or at column 0 (False)
get_lines()

Return lines to write out in order to show this widget.

Returns:lines representing this widget
Return type:list(str)
height

The current height of the internal buffer.

key_pattern

Return key pattern which will be used for items numbering.

Will return None if not set.

process_user_input(key)

Process input from the user if any of the items in the list was called.

This method must be called in UIScreen.input() method if list widget should call the callbacks.

Parameters:key (str) – Key pressed from user.
Returns:True if key was processed. False otherwise.
render(width)

Render widgets to it’s internal buffer.

Parameters:width (int) – the maximum width the item can use
Returns:nothing
set_cursor_position(row, col)

Set cursor position.

Parameters:
  • row (int) – row id, starts with 0 at the top of the screen
  • col (int) – column id, starts with 0 on the left side of the screen
set_end()

Set the cursor to first column in new line at the end.

size

Return items count.

width

The current width of the internal buffer (id of the first empty column).

write(text, row=None, col=None, width=None, block=False, wordwrap=False)

Emulate the typing machine writing to this widget’s buffer.

Parameters:
  • text (str) – text to type
  • row (int) – row number to start at (default is at the cursor position)
  • col (int) – column number to start at (default is at the cursor position)
  • width (int) – wrap at “col” + “width” column (default is at self._max_width)
  • block (boolean) – when printing newline, start at column col (True) or at column 0 (False)
  • wordwrap (boolean) – wrap by words
class simpleline.render.containers.ListColumnContainer(columns, items=None, columns_width=None, spacing=3, numbering=True)

Bases: simpleline.render.containers.ListRowContainer

Place widgets in columns automatically.

Compared to the ColumnWidget this is able to handle word wrapping correctly.

There is numbering N) automatically for all items. To disable this feature call self.key_pattern = None. If you want other numbering then look on KeyPattern class.

Widgets will be placed based on the number of columns in the following way:

  1. w1 4) w4 7) w7
  2. w2 5) w5 8) w8
  3. w3 6) w6 9) w9
add(item, callback=None, data=None)

Add item to the Container.

Parameters:
  • item (Could be item (based on simpleline.render.widgets.Widget) or other container (based on simpleline.render.containers.Container).) – Add item to this container.
  • callback (function func(data).) – Add callback for this item. This callback will be called when user activate this item.
  • data – Data which will be passed to the callback.
  • data – Anything.
Returns:

ID of the item in this Container.
Return type:

int
clear()

Clears this widgets buffer and resets cursor.

content

Return a list (rows) of lists (columns) with one character elements.

create_number_label(item_id)

Create TextWidget from KeyPattern.

Parameters:item_id (int) – Create label for item with this id.
Returns:Widget with label for the item with item_id.
Return type:simpleline.render.widgets.TextWidget instance.
draw(w, row=None, col=None, block=False)

Copy w widget’s content to this widget’s buffer at row, col position.

Parameters:
  • w (class Widget) – widget to take content from
  • row (int) – row number to start at (default is at the cursor position)
  • col (int) – column number to start at (default is at the cursor position)
  • block (boolean) – when printing newline, start at column col (True) or at column 0 (False)
get_lines()

Return lines to write out in order to show this widget.

Returns:lines representing this widget
Return type:list(str)
height

The current height of the internal buffer.

key_pattern

Return key pattern which will be used for items numbering.

Will return None if not set.

process_user_input(key)

Process input from the user if any of the items in the list was called.

This method must be called in UIScreen.input() method if list widget should call the callbacks.

Parameters:key (str) – Key pressed from user.
Returns:True if key was processed. False otherwise.
render(width)

Render widgets to it’s internal buffer.

Parameters:width (int) – the maximum width the item can use
Returns:nothing
set_cursor_position(row, col)

Set cursor position.

Parameters:
  • row (int) – row id, starts with 0 at the top of the screen
  • col (int) – column id, starts with 0 on the left side of the screen
set_end()

Set the cursor to first column in new line at the end.

size

Return items count.

width

The current width of the internal buffer (id of the first empty column).

write(text, row=None, col=None, width=None, block=False, wordwrap=False)

Emulate the typing machine writing to this widget’s buffer.

Parameters:
  • text (str) – text to type
  • row (int) – row number to start at (default is at the cursor position)
  • col (int) – column number to start at (default is at the cursor position)
  • width (int) – wrap at “col” + “width” column (default is at self._max_width)
  • block (boolean) – when printing newline, start at column col (True) or at column 0 (False)
  • wordwrap (boolean) – wrap by words
class simpleline.render.containers.WindowContainer(title=None)

Bases: simpleline.render.containers.Container

Base container for screens.

This can hold other containers or Widgets for rendering.

add(item, callback=None, data=None)

Add item to the Container.

Parameters:
  • item (Could be item (based on simpleline.render.widgets.Widget) or other container (based on simpleline.render.containers.Container).) – Add item to this container.
  • callback (function func(data).) – Add callback for this item. This callback will be called when user activate this item.
  • data – Data which will be passed to the callback.
  • data – Anything.
Returns:

ID of the item in this Container.
Return type:

int
add_separator(lines=1)

Add blank lines between widgets.

Parameters:lines (int greater than 0.) – How many blank lines should be printed.
add_with_separator(item, callback=None, data=None, blank_lines=1)

Add widget and after widget add blank line.

This method will call self.add(item, callback, data) self.add_separator(lines)

Parameters:
  • item (Could be item (based on simpleline.render.widgets.Widget) or other container (based on simpleline.render.containers.Container).) – Add item to this container.
  • callback (function func(data).) – Add callback for this item. This callback will be called when user activate this item.
  • data – Data which will be passed to the callback.
  • data – Anything.
  • blank_lines (int greater than 0.) – How many blank lines should be printed.
Returns:

ID of the item in this Container.
Return type:

int
clear()

Clears this widgets buffer and resets cursor.

content

Return a list (rows) of lists (columns) with one character elements.

create_number_label(item_id)

Create TextWidget from KeyPattern.

Parameters:item_id (int) – Create label for item with this id.
Returns:Widget with label for the item with item_id.
Return type:simpleline.render.widgets.TextWidget instance.
draw(w, row=None, col=None, block=False)

Copy w widget’s content to this widget’s buffer at row, col position.

Parameters:
  • w (class Widget) – widget to take content from
  • row (int) – row number to start at (default is at the cursor position)
  • col (int) – column number to start at (default is at the cursor position)
  • block (boolean) – when printing newline, start at column col (True) or at column 0 (False)
get_lines()

Return lines to write out in order to show this widget.

Returns:lines representing this widget
Return type:list(str)
height

The current height of the internal buffer.

key_pattern

Return key pattern which will be used for items numbering.

Will return None if not set.

process_user_input(key)

Process input from the user if any of the items in the list was called.

This method must be called in UIScreen.input() method if list widget should call the callbacks.

Parameters:key (str) – Key pressed from user.
Returns:True if key was processed. False otherwise.
render(width)

Render widgets to it’s internal buffer.

Parameters:width (int) – the maximum width the item can use
Returns:nothing
set_cursor_position(row, col)

Set cursor position.

Parameters:
  • row (int) – row id, starts with 0 at the top of the screen
  • col (int) – column id, starts with 0 on the left side of the screen
set_end()

Set the cursor to first column in new line at the end.

size

Return items count.

title

Title of WindowContainer.

width

The current width of the internal buffer (id of the first empty column).

write(text, row=None, col=None, width=None, block=False, wordwrap=False)

Emulate the typing machine writing to this widget’s buffer.

Parameters:
  • text (str) – text to type
  • row (int) – row number to start at (default is at the cursor position)
  • col (int) – column number to start at (default is at the cursor position)
  • width (int) – wrap at “col” + “width” column (default is at self._max_width)
  • block (boolean) – when printing newline, start at column col (True) or at column 0 (False)
  • wordwrap (boolean) – wrap by words

Creating a custom container

If an existing container is missing a required feature, a new, customized container can be created based on the Container class. Container creation is essentially the same as custom widget creation because containers are based on widgets. The main difference is that containers are working with widgets added by a developer when using the container. As an example, every UIScreen has a WindowContainer, and this is used as the main rendering point.

To create a customized container, the Container.render() method should be overridden and the positioning of widgets and containers should be done here. It can even enhance these widgets, for example, by adding numbering (this is done in ListRowContainer or ListColumnContainer). The Container.render() method should call the Container.draw() method. The Container.draw() method should be called for every widget placed. For a better understanding please refer to the existing implementation.

Base container class

class simpleline.render.containers.Container(items=None, numbering=True)

Bases: simpleline.render.widgets.Widget

Base class for containers which will do positioning of the widgets.

add(item, callback=None, data=None)

Add item to the Container.

Parameters:
  • item (Could be item (based on simpleline.render.widgets.Widget) or other container (based on simpleline.render.containers.Container).) – Add item to this container.
  • callback (function func(data).) – Add callback for this item. This callback will be called when user activate this item.
  • data – Data which will be passed to the callback.
  • data – Anything.
Returns:

ID of the item in this Container.
Return type:

int
clear()

Clears this widgets buffer and resets cursor.

content

Return a list (rows) of lists (columns) with one character elements.

create_number_label(item_id)

Create TextWidget from KeyPattern.

Parameters:item_id (int) – Create label for item with this id.
Returns:Widget with label for the item with item_id.
Return type:simpleline.render.widgets.TextWidget instance.
draw(w, row=None, col=None, block=False)

Copy w widget’s content to this widget’s buffer at row, col position.

Parameters:
  • w (class Widget) – widget to take content from
  • row (int) – row number to start at (default is at the cursor position)
  • col (int) – column number to start at (default is at the cursor position)
  • block (boolean) – when printing newline, start at column col (True) or at column 0 (False)
get_lines()

Return lines to write out in order to show this widget.

Returns:lines representing this widget
Return type:list(str)
height

The current height of the internal buffer.

key_pattern

Return key pattern which will be used for items numbering.

Will return None if not set.

process_user_input(key)

Process input from the user if any of the items in the list was called.

This method must be called in UIScreen.input() method if list widget should call the callbacks.

Parameters:key (str) – Key pressed from user.
Returns:True if key was processed. False otherwise.
render(width)

Redraw the widget’s self._buffer.

Parameters:width (int) – the width of buffer requested by the caller

Commonly, call render of child widgets and then draw and write methods to copy their contents to self._buffer.

set_cursor_position(row, col)

Set cursor position.

Parameters:
  • row (int) – row id, starts with 0 at the top of the screen
  • col (int) – column id, starts with 0 on the left side of the screen
set_end()

Set the cursor to first column in new line at the end.

size

Return items count.

width

The current width of the internal buffer (id of the first empty column).

write(text, row=None, col=None, width=None, block=False, wordwrap=False)

Emulate the typing machine writing to this widget’s buffer.

Parameters:
  • text (str) – text to type
  • row (int) – row number to start at (default is at the cursor position)
  • col (int) – column number to start at (default is at the cursor position)
  • width (int) – wrap at “col” + “width” column (default is at self._max_width)
  • block (boolean) – when printing newline, start at column col (True) or at column 0 (False)
  • wordwrap (boolean) – wrap by words