render#

This module implements the render logic of the terminal UI.

class zelfred.render.Render(terminal: ~blessed.terminal.Terminal = <factory>, line_number: int = 0, n_lines: int = 0)[source]#

Generic UI render. It can print string, print line, clear line, and move cursor up and down.

Parameters:

terminal – blessed terminal object.
line_number – store the current line number of the cursor. if 0, means it is at the first line. if 1, means it is at the second line.
n_lines – store the total number of printed lines in the terminal.

print_str(str_tpl: str, new_line=False, **kwargs) → str[source]#

打印一个字符串, 可以选择是否换行. 并且自动更新 line_number 的值.

Parameters:

str_tpl – string template, 一个字符串模板.
new_line – 如果是 True, 那么会自动换行, 否则不会. 默认不会.
kwargs – 额外的传递给 str_tpl 的参数.

print_line(str_tpl: str, new_line: bool = True, **kwargs) → str[source]#

打印一行, 默认自动换行.

Parameters:

str_tpl – string template, 一个字符串模板.
new_line – 如果是 True, 那么会自动换行, 否则不会. 默认自动换行.
kwargs – 额外的传递给 str_tpl 的参数.

move_to_start() → int[source]#: 把光标移动到初始位置. 本质上是把光标向上回退移动到第一行, 然后再用回车符把光标移动到本行初始位置.

move_up(n: int)[source]#: 把光标移动到初始位置. 本质上是把光标向上回退移动到第一行, 然后再用回车符把光标移动到本行初始位置.

move_down(n: int)[source]#: 把光标移动到初始位置. 本质上是把光标向上回退移动到第一行, 然后再用回车符把光标移动到本行初始位置.

clear_n_lines(n: int)[source]#: 把光标以上的 n 行清空, 并把光标移动到行首. 常用于清除掉已经打印过的内容.

clear_all()[source]#

清除所有内容, 并把光标移动到行首.

Clear

format_shortcut(key: str) → str[source]#

Add terminal color to a zelfred keyboard shortcut key.

The default color is magenta. You can override this method to use other colors.

Example:

Tap Enter to open url

property TAB: str#: colored text Tab

property ENTER: str#: colored text Enter

property CTRL_A: str#: colored text Ctrl A

property CTRL_W: str#: colored text Ctrl W

property CTRL_U: str#: colored text Ctrl U

property CTRL_P: str#: colored text Ctrl P

property F1: str#: colored text F1

format_highlight(text: str) → str[source]#

Add terminal color to text you want to highlight.

The default color is magenta. You can override this method to use other colors.

Example:

this is a very Important message!

format_key(key: str) → str[source]#

Add terminal color to key in a key value pair.

The default color is cyan. You can override this method to use other colors.

format_value(value: str) → str[source]#

Add terminal color to value in a key value pair.

The default color is yellow. You can override this method to use other colors.

format_key_value(key: str, value: str) → str[source]#

Add terminal color to a key value pair.

Example:

tag environment = production

class zelfred.render.UIRender(terminal: ~blessed.terminal.Terminal = <factory>, line_number: int = 0, n_lines: int = 0, prompt: str = '(Query)', checked_mark: str = '[x]', not_checked_mark: str = '[ ]', subtitle_pad: str = ' ')[source]#

The Terminal UI Render. It extends the Render class and highly optimized for the zelfred terminal UI layout.

See below example, | represents the cursor:

(Query): user query here|
[x] item 1 title here
      item 1 subtitle here
[ ] item 2 title here
      item 2 subtitle here
[ ] item 3 title here
      item 3 subtitle here

The first line (Query): user query here| is the user input box, it always starts with ``(Query): ``, and user can enter any text input after that. The cursor cannot go beyond the ``: `` part.

User can use Left, Right, Backspace and Delete keys to edit the user input box.

Below the first line is the items drop down menu. Each item has two lines.

The first line is the title, it always starts with ``[x] `` or ``[ ] ``. ``[x] `` means the item is selected, ``[ ] `` means the item is not selected. You can only select one item at a time, and by default the first item is selected. There always be one item selected.

The second line is the subtitle, it has 2 indent spaces comparing to the title.

User can use the UP and DOWN keys to navigate the items drop down menu.

The dropdown menu can show up to 10 items at a time, if the dropdown menu has more than 10 items, user can scroll down to see the rest of the items using the DOWN key. The CTRL + UP and CTRL + DOWN key can scroll up and down 10 items at a time.

print_line_editor(line_editor: LineEditor) → str[source]#

Render the line editor, the (Query): user query here| part. And move the cursor to the beginning of the next line, so it’s ready to print the dropdown menu.

It assumes that there is nothing in the terminal UI before running this.

Parameters:: line_editor – the new LineEditor object.
Returns:: text of the line editor.

clear_line_editor()[source]#

Clear the line editor (the query input box at the first line). It doesn’t require to move the cursor to the beginning of the line editor before calling this function, it will handle that automatically. This function will move the cursor to the beginning of the line editor at the end.

Before:

(Query): user query here|
[x] item 1 title here
      item 1 subtitle here
[ ] item 2 title here
      item 2 subtitle here
[ ] item 3 title here
      item 3 subtitle here

Before:

|   # <- this line is empty
[x] item 1 title here
      item 1 subtitle here
[ ] item 2 title here
      item 2 subtitle here
[ ] item 3 title here
      item 3 subtitle here

update_line_editor(line_editor: LineEditor) → str[source]#

Replace the user input with the new line editor, and move the cursor to the beginning of the next line, so it’s ready to print the dropdown menu.

Parameters:: line_editor – the new LineEditor object.
Returns:: text of the line editor.

process_title(title: str, line_width: int)[source]#

Make sure the title fix the width of the terminal UI.

Parameters:

title – the item title.
line_width – the max width of the terminal UI, it will truncate the title and subtitle if they are too long.

process_subtitle(subtitle: str, line_width: int)[source]#

Make sure the subtitle fix the width of the terminal UI.

Parameters:

subtitle – the item subtitle.
line_width – the max width of the terminal UI, it will truncate the title and subtitle if they are too long.

print_item(item: T_ITEM, selected: bool, line_width: int)[source]#

Render one item in the dropdown menu. It looks like:

[x] item 1 title here
    - item 1 subtitle here

Parameters:

item – the Item object to render.
line_width – the max width of the terminal UI, it will truncate the title and subtitle if they are too long.

print_dropdown(dropdown: Dropdown, line_width: int) → int[source]#

Render all items in the dropdown menu, it looks like:

[x] item 1 title here
      item 1 subtitle here
[ ] item 2 title here
      item 2 subtitle here
[ ] item 3 title here
      item 3 subtitle here

It assumes that the terminal UI is showing the query line editor and there’s no item in the dropdown menu in the terminal UI before running this.

Parameters:

dropdown – the Dropdown object to render.
line_width – the max width of the terminal UI, it will truncate the title and subtitle if they are too long.

Returns:

number of items rendered.

clear_dropdown()[source]#

Before:

(Query): user query here|
[x] item 1 title here
      item 1 subtitle here
[ ] item 2 title here
      item 2 subtitle here
[ ] item 3 title here
      item 3 subtitle here

Before:

(Query): user query here
|

update_dropdown(dropdown: Dropdown, line_width: int) → int[source]#

Replace the user input with the new line editor, and move the cursor to the beginning of the next line, so it’s ready to print the dropdown menu.

Parameters:

dropdown – the Dropdown object to render.
line_width – the max width of the terminal UI, it will truncate the title and subtitle if they are too long.

Returns:

number of items rendered.

move_cursor_to_line_editor(line_editor: LineEditor) → Tuple[int, int][source]#

After the Dropdown.print_dropdown() is called, the cursor is at the end of the UI. This method moves the cursor back to the user input box, so user can keep typing.

Here’s an example:

(Query): user query here| <- want to move to here
[x] item 1 title here
      item 1 subtitle here
[ ] item 2 title here
      item 2 subtitle here
[ ] item 3 title here
      item 3 subtitle here
| <- cursor is currently here

Returns:: n_vertical is the number of line to move up, n_horizontal is the number of character to move right.

print_ui(line_editor: LineEditor, dropdown: Dropdown) → int[source]#

Render the entire UI, and move the cursor to the right position.

It assumes the terminal has nothing.

move_to_end() → int[source]#

Move the cursor to the end, this method will be used before exit. Here’s an example:

(Query): user query here| <- cursor is currently here
[x] item 1 title here
      item 1 subtitle here
[ ] item 2 title here
      item 2 subtitle here
[ ] item 3 title here
      item 3 subtitle here
| <- want to move to here

Parameters:: n_items – number of items in the dropdown menu.

clear_ui()[source]#: Clear the entire UI, and move the cursor to the right position.