Building an inline-widget context
Our objective today will be to implement a function that lets us use PyTermGUI widgets in an inline-context, e.g. from the terminal prompt while retaining the shell's state.
This type of usage is common for simple prompts that are part of a greater, CLI-based application; they give you the cool-factor of the TUI, and in our case its mouse & keyboard input options, while staying in a CLI environment.
Defining our goals
Our target syntax will be this:
prompt_widget = ptg.inline(built_prompt())
...which gives us the general signature:
def inline(widget):
...
return widget
Basic implementation
Let's start with getting the widget to read keyboard inputs and render after each one of them. To do this, we will sit in a while loop, use the getch function and send its output to our widget's handle_key method.
from pytermgui import getch, Widget
def inline(widget):
while True:
key = getch()
widget.handle_key(key)
for line in widget.get_lines():
print(line)
return widget
If you run the above, you will notice 2 things:
- Pressing Ctrl+C leaves us with an ugly
KeyboardInterrupt - The widget lines aren't overwritten, but written to the terminal sequentially
There is also no mouse interaction, but we'll leave that for later.
Implementing clean exits
Let's focus on our first problem, relating to the KeyboardInterrupt error. This is trivial to fix; we can tell getch to convert KeyboardInterrupt into the character Ctrl+C sends, and break the loop when we see said character.
The reason we need to do this lies deep in the trenches of the terminal, but here is the gist: When Ctrl+C is detected, the "interrupt" signal is sent to the current foreground task. This signal (in simple terms) tells the program:
Hey there! I think you should stop running.
It's important to note that this is not a full hard drop everything you're doing and flee signal. This one is meant to allow programs to clean up after themselves before quitting, which is exactly what we will need to do.
Note
To see the above in effect, you can try the following code:
from time import time
while True:
try:
print(time())
except KeyboardInterrupt:
pass
return widget
You will now be unable to leave the program, haha! Just kidding. Press Ctrl+\ to send the "kill" signal to the program, which will stop the loop in its tracks. You can also press Ctrl+L, or type reset into the shell if your terminal got too messed up.
I feel like this goes without saying, but:
Please do not put inescapable loops into your code
from typing import TypeVar
- from pytermgui import getch, Widget
+ from pytermgui import getch, keys, Widget
T = TypeVar("T", bound=Widget)
def inline(widget):
while True:
- key = getch()
+ key = getch(interrupts=False)
+
+ if key == keys.CTRL_C:
+ break
widget.handle_key(key)
for line in widget.get_lines():
print(line)
return widget
| inline.py | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
If you now run this and press Ctrl+C, you should see the program quit cleanly.
Improving printing
The print routine above was pretty rudimentary. We can do better!
To achieve the 'prompt' look we are aiming for, we need to always start printing at the same location. The simplest way to do this is to use the save_cursor and restore_cursor methods. These tell the terminal to store the current cursor location somewhere, and to move the cursor to the stored location, respectively.
Let's start by making the following changes:
from typing import TypeVar
- from pytermgui import getch, keys, Widget
+ from pytermgui import getch, keys, save_cursor, restore_cursor, Widget
def inline(widget):
while True:
key = getch(interrupts=False)
if key == keys.CTRL_C:
break
widget.handle_key(key)
+ save_cursor()
+
for line in widget.get_lines():
print(line)
+
+ restore_cursor()
return widget
| inline.py | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | |
This fixes the issue, but you may notice our widget only gets printed after the first input. That happens because we call getch before the first prints. Let's fix it, and also move the printing logic into an inner function to make things cleaner:
from typing import TypeVar
from pytermgui import getch, keys, save_cursor, restore_cursor, Widget
def inline(widget):
+ def _print_widget():
+ save_cursor()
+
+ for line in widget.get_lines():
+ print(line)
+
+ restore_cursor()
+
+ _print_widget()
+
while True:
key = getch(interrupts=False)
if key == keys.CTRL_C:
break
widget.handle_key(key)
+ _print_widget()
- save_cursor()
-
- for line in widget.get_lines():
- print(line)
-
- restore_cursor()
return widget
| inline.py | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | |
You may have noticed that when exiting, part of the widget remains on the screen. This is the last print-related issue we need to fix!
We can use the clear function with the "line" parameter to clear all the affected lines of the terminal.
Let's introduce a new inner function, _clear_widget:
15 16 17 18 19 20 21 22 23 | |
- We need to increment the cursor using newlines to make sure we aren't just clearing the same line over and over.
To include this, we need to import both clear and terminal. We also probably want to call our new function, specifically before the call to print and at the end of our inline routine.
Here is a snapshot of our work so far:
from typing import TypeVar
- from pytermgui import getch, keys, save_cursor, restore_cursor, Widget
+ from pytermgui import (
+ getch,
+ keys,
+ save_cursor,
+ restore_cursor,
+ Widget,
+ clear,
+ get_terminal,
+ )
def inline(widget):
+ # Make sure we use the global terminal
+ terminal = get_terminal()
+
def _print_widget():
save_cursor()
for line in widget.get_lines():
print(line)
restore_cursor()
+ def _clear_widget():
+ save_cursor()
+
+ for _ in range(widget.height):
+ clear("line")
+ terminal.write("\n")
+
+ restore_cursor()
+ terminal.flush()
_print_widget()
while True:
key = getch(interrupts=False)
if key == keys.CTRL_C:
break
widget.handle_key(key)
+ _clear_widget()
_print_widget()
+
+ _clear_widget()
return widget
| inline.py | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 | |
And with that, our printing routine is exactly how we want it to be! Now onto the fancy things.
Mouse support
Traditionally, mouse support is the "big bad" enemy of writing terminal programs. However, PyTermGUI makes it a lot easier than you would've thought!
The only new thing we will need to import is the mouse_handler context manager. This function does 2 things:
- Tells the terminal to send mouse events
- Returns a function that can translate mouse codes into MouseEvent instances
To use it, we will wrap our while True loop into the context, and try to handle keys as mouse events when our widget didn't handle them successfully. Each widget denotes "successful" event handling by returning True from the given method, so the check will be simple:
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 | |
There is a tiny bug with our mouse handling, however. We never tell the widget where it is located, so it will reject most events. We can easily fix this by using the report_mouse and inserting the following line at the top of our function:
widget.pos = report_cursor()
With the above changes, our file looks like the following:
| inline.py | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 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 | |
Congratulations!
You just implemented PyTermGUI's inline function!
Make sure to look at its source code for the final version of the code we've been working with, along with a few extra improvements, such as handling each the widget's positioned_line_buffer.