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:
-
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:
-
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:
-
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:
-
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:
- 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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
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
-