Skip to content

components

dev_tool.tui.components

__all__ = ['HeaderComponent', 'ItemComponent', 'NavigationHandler', 'NotificationComponent', 'StateManager', 'StatusBarComponent', 'TabComponent'] module-attribute

HeaderComponent

A component for rendering the header.

The constructor for the HeaderComponent class.

Parameters:

  • terminal (Terminal) –

    The blessed Terminal instance.

  • theme (Default) –

    The theme instance for styling.

Source code in dev_tool/tui/components/header.py 
16
17
18
19
20
21
22
23
24
25
26
def __init__(self, terminal: Terminal, theme: Default) -> None:
    """
    The constructor for the HeaderComponent class.

    :param terminal: The blessed Terminal instance.
    :param theme: The theme instance for styling.
    """

    self.project = CONTEXT.configuration.get_project_name() or 'Unknown'
    self.terminal = terminal
    self.theme = theme

project = CONTEXT.configuration.get_project_name() or 'Unknown' instance-attribute

terminal = terminal instance-attribute

theme = theme instance-attribute

draw

A method that draws the header with the project title.

Parameters:

  • output (list) –

    The list to append terminal output strings to.

Source code in dev_tool/tui/components/header.py 
28
29
30
31
32
33
34
35
36
37
38
39
def draw(self, output: list) -> None:
    """
    A method that draws the header with the project title.

    :param output: The list to append terminal output strings to.
    """

    background = ' ' * self.terminal.width
    output.append(self.terminal.move(0, 0) + self.theme.header_background(background))

    title = f' {self.project}'
    output.append(self.terminal.move(0, 0) + self.theme.header_background(title))

ItemComponent

A component for rendering the menu items.

The constructor for the ItemComponent class.

Parameters:

  • terminal (Terminal) –

    The blessed Terminal instance.

  • theme (Default) –

    The theme instance for styling.

  • state (StateManager) –

    The state manager instance.

Source code in dev_tool/tui/components/item.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
def __init__(self, terminal: Terminal, theme: Default, state: StateManager) -> None:
    """
    The constructor for the ItemComponent class.

    :param terminal: The blessed Terminal instance.
    :param theme: The theme instance for styling.
    :param state: The state manager instance.
    """

    self.notification = NotificationDisplay(terminal)
    self.state = state
    self.terminal = terminal
    self.theme = theme

notification = NotificationDisplay(terminal) instance-attribute

state = state instance-attribute

terminal = terminal instance-attribute

theme = theme instance-attribute

draw

A method that draws the menu items.

Parameters:

  • output (list) –

    The list to append terminal output strings to.

Source code in dev_tool/tui/components/item.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def draw(self, output: list) -> None:
    """
    A method that draws the menu items.

    :param output: The list to append terminal output strings to.
    """

    lines = self.notification.get_notification_lines()
    length = len(lines)

    if self.state.is_root_with_tabs():
        start = 5 + length
        selected = self.state.menu.items[self.state.index]
        items = selected.get_items()
    else:
        start = (5 if self.state.is_tabs() else 4) + length
        items = self.state.menu.items

    available = self.terminal.height - start - 2
    total = len(items)

    if not items:
        message = '    No item(s) available'
        line = start
        output.append(self.terminal.move(line, 0) + self.theme.command_text(message))
        return

    self.state.offset = min(self.state.row, self.state.offset)

    if self.state.row >= self.state.offset + available:
        self.state.offset = self.state.row - available + 1

    minimum = min(total, self.state.offset + available)

    for index in range(self.state.offset, minimum):
        item = items[index]

        if item.as_menu():
            continue

        line = start + (index - self.state.offset)
        selected = index == self.state.row
        menuitem = item.as_menu_item()

        if menuitem:
            submenu = menuitem.action.is_submenu()

            suffix = ' ↵' if submenu else ''
            text = f'    {menuitem.label}{suffix}'

            if selected and submenu:
                background = ' ' * self.terminal.width
                output.append(self.terminal.move(line, 0) + self.theme.selected_menu_background(background))
                output.append(self.terminal.move(line, 0) + self.theme.selected_menu_background(text))

            if selected and not submenu:
                background = ' ' * self.terminal.width
                output.append(self.terminal.move(line, 0) + self.theme.selected_command_background(background))
                output.append(self.terminal.move(line, 0) + self.theme.selected_command_background(text))

            if not selected and submenu:
                output.append(self.terminal.move(line, 0) + self.theme.menu_text(text))

            if not selected and not submenu:
                output.append(self.terminal.move(line, 0) + self.theme.command_text(text))

NavigationHandler

A handler class for navigation logic.

The constructor for the NavigationHandler class.

Parameters:

Source code in dev_tool/tui/components/navigation.py 
16
17
18
19
20
21
22
23
24
25
def __init__(self, state: StateManager, notification: NotificationDisplay) -> None:
    """
    The constructor for the NavigationHandler class.

    :param state: The state manager instance.
    :param notification: The notification display instance.
    """

    self.notification = notification
    self.state = state

notification = notification instance-attribute

state = state instance-attribute

get_selected_item

A method that gets the currently selected menu item.

Returns:

Source code in dev_tool/tui/components/navigation.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
def get_selected_item(self) -> MenuItem:
    """
    A method that gets the currently selected menu item.

    :return: The selected menu item.
    """

    if self.state.is_root_with_tabs():
        selected = self.state.menu.items[self.state.index]
        menu = selected.as_menu()

        if menu:
            item = menu.items[self.state.row].as_menu_item()

            if item:
                return item

            message = 'Expected MenuItem in menu'
            raise ValueError(message)

        message = 'Expected Menu in tab position'
        raise ValueError(message)

    item = self.state.menu.items[self.state.row].as_menu_item()

    if item:
        return item

    message = 'Expected MenuItem'
    raise ValueError(message)

handle_navigation

A method that handles navigation key presses.

Parameters:

  • key (str) –

    The key name.

Returns:

  • bool –

    True if the UI needs redraw, False otherwise.

Source code in dev_tool/tui/components/navigation.py 
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def handle_navigation(self, key: str) -> bool:
    """
    A method that handles navigation key presses.

    :param key: The key name.
    :return: True if the UI needs redraw, False otherwise.
    """

    if self._handle_notification_dismissal(key):
        return True

    if self._handle_submenu(key):
        return True

    self._handle_navigation_keys(key)
    return True

NotificationComponent

A component for rendering notifications.

The constructor for the NotificationComponent class.

Parameters:

  • terminal (Terminal) –

    The blessed Terminal instance.

Source code in dev_tool/tui/components/notification.py 
14
15
16
17
18
19
20
21
22
def __init__(self, terminal: Terminal) -> None:
    """
    The constructor for the NotificationComponent class.

    :param terminal: The blessed Terminal instance.
    """

    self.notification = NotificationDisplay(terminal)
    self.terminal = terminal

notification = NotificationDisplay(terminal) instance-attribute

terminal = terminal instance-attribute

draw

A method that draws notification banners below the header.

Parameters:

  • output (list) –

    The list to append terminal output strings to.

Source code in dev_tool/tui/components/notification.py 
24
25
26
27
28
29
30
31
32
33
34
def draw(self, output: list) -> None:
    """
    A method that draws notification banners below the header.

    :param output: The list to append terminal output strings to.
    """

    lines = self.notification.get_notification_lines()

    for index, line in enumerate(lines):
        output.append(self.terminal.move(2 + index, 0) + line)

get_notification_lines

A method that gets the current notification lines.

Returns:

  • list –

    The list of notification lines.

Source code in dev_tool/tui/components/notification.py 
36
37
38
39
40
41
42
43
def get_notification_lines(self) -> list:
    """
    A method that gets the current notification lines.

    :return: The list of notification lines.
    """

    return self.notification.get_notification_lines()

StateManager

A class for managing TUI state and navigation stack.

The constructor for the StateManager class.

Source code in dev_tool/tui/components/state.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def __init__(self) -> None:
    """The constructor for the StateManager class."""

    menu = MenuFactory.create_main_menu()

    self.stack = [
        State(
            menu=menu,
            index=0,
            row=0,
            offset=0,
            tab=0
        )
    ]

stack = [State(menu=menu, index=0, row=0, offset=0, tab=0)] instance-attribute

current property

A property that gets the current state.

Returns:

  • State –

    The current state.

index property writable

A property that gets the current selected index.

Returns:

  • int –

    The current index.

menu property

A property that gets the current menu.

Returns:

  • Menu –

    The current menu.

offset property writable

A property that gets the current scroll offset.

Returns:

  • int –

    The current offset.

root property

A property that gets the root menu.

Returns:

  • Menu –

    The root menu.

row property writable

A property that gets the current row.

Returns:

  • int –

    The current row.

tab property writable

A property that gets the current tab index.

Returns:

  • int –

    The current tab index.

go_back

A method that navigates back to the previous menu.

Source code in dev_tool/tui/components/state.py 
185
186
187
188
189
def go_back(self) -> None:
    """A method that navigates back to the previous menu."""

    if len(self.stack) > 1:
        self.stack.pop()

is_root_with_tabs

A method that checks if currently at root level with tabs.

Returns:

  • bool –

    True if at root with tabs, False otherwise.

Source code in dev_tool/tui/components/state.py 
191
192
193
194
195
196
197
198
def is_root_with_tabs(self) -> bool:
    """
    A method that checks if currently at root level with tabs.

    :return: True if at root with tabs, False otherwise.
    """

    return len(self.stack) == 1 and self.is_tabs()

is_tabs

A method that checks if the current menu has tabs.

Returns:

  • bool –

    True if the menu has tabs, False otherwise.

Source code in dev_tool/tui/components/state.py 
200
201
202
203
204
205
206
207
208
209
210
def is_tabs(self) -> bool:
    """
    A method that checks if the current menu has tabs.

    :return: True if the menu has tabs, False otherwise.
    """

    if not self.root.items:
        return False

    return self.root.items[0].as_menu() is not None

push_menu

A method that pushes a new menu onto the stack.

Parameters:

  • menu (Menu) –

    The new menu.

Source code in dev_tool/tui/components/state.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
def push_menu(self, menu: Menu) -> None:
    """
    A method that pushes a new menu onto the stack.

    :param menu: The new menu.
    """

    if menu is self.menu:
        return

    current = self.index if self.is_root_with_tabs() else self.tab

    state = State(
        menu=menu,
        index=0,
        row=0,
        offset=0,
        tab=current
    )

    self.stack.append(state)

StatusBarComponent

A component for rendering the status bar.

The constructor for the StatusBarComponent class.

Parameters:

  • terminal (Terminal) –

    The blessed Terminal instance.

  • theme (Default) –

    The theme instance for styling.

  • state (StateManager) –

    The state manager instance.

Source code in dev_tool/tui/components/status_bar.py 
17
18
19
20
21
22
23
24
25
26
27
28
def __init__(self, terminal: Terminal, theme: Default, state: StateManager) -> None:
    """
    The constructor for the StatusBarComponent class.

    :param terminal: The blessed Terminal instance.
    :param theme: The theme instance for styling.
    :param state: The state manager instance.
    """

    self.state = state
    self.terminal = terminal
    self.theme = theme

state = state instance-attribute

terminal = terminal instance-attribute

theme = theme instance-attribute

draw

A method that draws the status bar with navigation info.

Parameters:

  • output (list) –

    The list to append terminal output strings to.

Source code in dev_tool/tui/components/status_bar.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def draw(self, output: list) -> None:
    """
    A method that draws the status bar with navigation info.

    :param output: The list to append terminal output strings to.
    """

    line = self.terminal.height - 1
    left = self._get_left_content()
    right = self._get_right_content()
    middle = self._get_middle_content()
    status = self._format_layout(left, middle, right)

    background = ' ' * self.terminal.width

    output.append(self.terminal.move(line, 0) + self.theme.status_bar(background))
    output.append(self.terminal.move(line, 0) + self.theme.status_bar(status))

TabComponent

A component for rendering the tabs.

The constructor for the TabComponent class.

Parameters:

  • terminal (Terminal) –

    The blessed Terminal instance.

  • theme (Default) –

    The theme instance for styling.

  • state (StateManager) –

    The state manager instance.

Source code in dev_tool/tui/components/tab.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
def __init__(self, terminal: Terminal, theme: Default, state: StateManager) -> None:
    """
    The constructor for the TabComponent class.

    :param terminal: The blessed Terminal instance.
    :param theme: The theme instance for styling.
    :param state: The state manager instance.
    """

    self.notification = NotificationDisplay(terminal)
    self.state = state
    self.terminal = terminal
    self.theme = theme

notification = NotificationDisplay(terminal) instance-attribute

state = state instance-attribute

terminal = terminal instance-attribute

theme = theme instance-attribute

draw

A method that draws the tab navigation if applicable.

Parameters:

  • output (list) –

    The list to append terminal output strings to.

Source code in dev_tool/tui/components/tab.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def draw(self, output: list) -> None:
    """
    A method that draws the tab navigation if applicable.

    :param output: The list to append terminal output strings to.
    """

    if not self.state.is_tabs():
        return

    lines = len(self.notification.get_notification_lines())
    line = 3 + lines

    background = ' ' * self.terminal.width

    output.append(
        self.terminal.move(line, 0) +
        self.theme.tab_unselected(background)
    )

    tabs = self.state.root.items
    current = self.state.tab

    x = 0

    for index, item in enumerate(tabs):
        text = f'  {item.label}  '

        if index == current:
            output.append(
                self.terminal.move(line, x) +
                self.theme.tab_selected(text)
            )
        else:
            output.append(
                self.terminal.move(line, x) +
                self.theme.tab_unselected(text)
            )

        x = x + len(text)

        if x >= self.terminal.width - 20:
            break