Widgets

Widgets are the basic units to render items on a screen. Widgets can wrap a common text (TextWidget) or create empty lines (SeparatorWidget). They can also be more complex structures (CheckboxWidget). A new widget can also be created. See Creating a custom widget.

These widgets should be used in Containers.

Widgets classes

class simpleline.render.widgets.TextWidget(text)

Bases: simpleline.render.widgets.Widget

Class to handle wrapped text output.

clear()

Clears this widgets buffer and resets cursor.

content

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

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.

render(width)

Renders the text widget limited to width number of columns.

Wraps to the next line when the text is longer.

Parameters:width (int) – maximum width allocated to the string
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.

text

Contains text of this widget.

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.widgets.SeparatorWidget(lines=1)

Bases: simpleline.render.widgets.Widget

Print empty line.

clear()

Clears this widgets buffer and resets cursor.

content

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

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.

render(width)

Render empty line to the buffer.

Parameters:width (int) – maximum width allocated to the string
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.

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)

Optimize write function.

To print just a blank line we don’t need too much logic.

class simpleline.render.widgets.EntryWidget(title, value=None)

Bases: simpleline.render.widgets.TextWidget

This is the easy way how to generate entry items for containers.

If the numbering in a container is turned on the output looks like:

  1. title value

Without numbering turned on:

title value

clear()

Clears this widgets buffer and resets cursor.

content

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

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.

render(width)

Renders the text widget limited to width number of columns.

Wraps to the next line when the text is longer.

Parameters:width (int) – maximum width allocated to the string
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.

text

Contains text of this widget.

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.widgets.CheckboxWidget(key='x', title=None, text=None, completed=None)

Bases: simpleline.render.widgets.Widget

Widget to show checkbox with (un)checked box, name and description.

clear()

Clears this widgets buffer and resets cursor.

completed

Returns the state of the checkbox, checked is True.

content

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

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.

render(width)

Render the widget to internal buffer.

It should be max width characters wide.

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.

text

Contains the description text from the second line.

title

Returns the first line (main title) of the checkbox.

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.widgets.CenterWidget(w)

Bases: simpleline.render.widgets.Widget

Class to handle horizontal centering of content.

clear()

Clears this widgets buffer and resets cursor.

content

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

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.

render(width)

Render the centered widget to internal buffer.

Parameters:width (int) – maximum width the widget should use
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.

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 widget

To create a custom widget you should subclass the Widget class. The most important method for creating a customized widget is Widget.render(). This method is responsible for presenting a user textual information.

If the new widget is composed of other widgets the Widget.draw() method should be called on every widget used. The Widget.write() method should be called if the input is a string. These calls can be repeated multiple times. For an example please look at the existing implementation.

Base Widget class

class simpleline.render.widgets.Widget(max_width=None, default=None)

Bases: object

clear()

Clears this widgets buffer and resets cursor.

content

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

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.

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.

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