📂 tui

tui::clearBox

Clear a “box” in the terminal. Will return the cursor at the current position at the end (using GLOBAL_CURSOR_LINE and GLOBAL_CURSOR_COLUMN).

• $1: top as int: the left position of the box
• $2: left as int: the top position of the box
• $3: width as int: the width of the box
• $4: height as int: the height of the box

tui::getCursorPosition
tui::clearBox 1 1 10 5

tui::clearKeyPressed

This function reads all the inputs from the user, effectively discarding them.

tui::clearKeyPressed

tui::createSpace

This function creates empty lines from the current cursor position. Then it moves back to its original line (at the column 1). The current cursor line counts, meaning that tui::createSpace 1 will not do anything but clear the current line.

This effectively creates a space in the terminal (scroll up if we are at the bottom). It does not create more space than the number of lines in the terminal.

• $1: number of lines as int: the number of lines to create

tui::createSpace 5

tui::getBestAutocompleteBox

This function returns the best position and size for an autocomplete box that would open at the given position.

• The box will be placed below the current position if possible, but can be placed above if there is not enough space below.

• The box will be placed on the same column as the current position if possible, but can be placed on the left side if there is not enough space on the right to display the full width of the box.

• The box will have the desired height and width if possible, but will be reduced if there is not enough space in the terminal.

• The box will not be placed on the same line as the current position if notOnCurrentLine is set to true. Otherwise it can use the current position line.

• $1: current line as int: the current line of the cursor (1 based)

• $2: current column as int: the current column of the cursor (1 based)

• $3: desired height as int: the desired height of the box

• $4: desired width as int: the desired width of the box

• $5: max height as int: the maximum height of the box

• $6: force below as bool: (optional) force the box to be below the current position (defaults to false)

• $7: not on current line as bool: (optional) the box will not be placed on the same line as the current position (defaults to true)

• $8: terminal width as int: (optional) the width of the terminal (defaults to GLOBAL_COLUMNS)

• $9: terminal height as int: (optional) the height of the terminal (defaults to GLOBAL_LINES)

Returns:

• ${RETURNED_VALUE}: the top position of the box (1 based)
• ${RETURNED_VALUE2}: the left position of the box (1 based)
• ${RETURNED_VALUE3}: the width of the box
• ${RETURNED_VALUE4}: the height of the box

tui::getBestAutocompleteBox 1 1 10 5

tui::getCursorPosition

Get the current cursor position.

Returns:

• GLOBAL_CURSOR_LINE: the line number
• GLOBAL_CURSOR_COLUMN: the column number

tui::getCursorPosition

tui::getTerminalSize

This function exports the terminal size.

Returns:

• GLOBAL_COLUMNS: The number of columns in the terminal.
• GLOBAL_LINES: The number of lines in the terminal.

tui::getTerminalSize
printf '%s\n' "The terminal has ⌜${GLOBAL_COLUMNS}⌝ columns and ⌜${GLOBAL_LINES}⌝ lines."

tui::rebindKeymap

Rebinds all special keys to call a given callback function. See @tui::testWaitForKeyPress for an implementation example.

This allows to use the -e option with the read command and receive events for special key press.

Key binding is a mess because binding is based on the sequence of characters that gets generated by the terminal when a key is pressed and this is not standard across all terminals. We do our best here to cover most cases but it is by no mean perfect. A good base documentation was https://en.wikipedia.org/wiki/ANSI_escape_code#Terminal_input_sequences.

This function should be called before using tui::waitForKeyPress.

You can call tui::restoreBindings to restore the default bindings. However, this is not necessary as the bindings are local to the script.

• $1: callback function as string: The function name to call when a special key is pressed.

tui::rerouteLogs

Reroute the logs to a temporary file. The logs will be displayed when calling tui::restoreLogs

tui::rerouteLogs

tui::restoreBindings

Reset the key bindings to the default ones. To be called after tui::rebindKeymap.

tui::restoreBindings

tui::restoreInterruptTrap

Restore the original trap for the interrupt signal (SIGINT). To be called after tui::setInterruptTrap.

tui::restoreInterruptTrap

tui::restoreLogs

Restore the logs to their original state. Should be called after tui::rerouteLogs and at the end of an interactive session.

tui::restoreLogs

tui::restoreTerminalOptions

Restore the terminal options to their original state. Should be called after tui::setTerminalOptions.

• $1: force as bool: (optional) force the restoration of the stty configuration. By default, the restoration is only done if we are not in full screen mode when called. (defaults to false)

tui::restoreTerminalOptions

tui::setInterruptTrap

Set a trap to catch the interrupt signal (SIGINT). When the user presses Ctrl+C, the GLOBAL_SESSION_INTERRUPTED variable will be set to true.

tui::setInterruptTrap

tui::setTerminalOptions

Set the terminal options to enable a satisfying and consistent behavior for the GNU readline library. Disable the echo of the terminal, no longer display the characters typed by the user.

tui::setTerminalOptions

tui::switchBackFromFullScreen

Call this function to switch back from the full screen mode.

• This function will restore the terminal state and show the cursor.
• It will also restore the key echoing.

tui::switchBackFromFullScreen

tui::switchToFullScreen

Call this function to start an interactive session in full screen mode. This function will switch to the alternate screen, hide the cursor and clear the screen.

You should call tui::switchBackFromFullScreen at the end of the interactive session.

tui::switchToFullScreen

tui::testWaitForChar

Wait for the user to send a character to stdin (i.e. wait for a key press) and prints the character that bash reads.

Useful to test the tui::waitForChar function and see the char sequence we get when pressing a key in a given terminal.

See @tui::waitForChar for more information.

tui::testWaitForChar

tui::testWaitForKeyPress

Wait for the user to press a key and prints it to the screen. This function is used to test the tui::waitForKeyPress function.

See @tui::waitForKeyPress for more information.

tui::testWaitForKeyPress

tui::waitForChar

Wait for a user input (single char). You can pass additional parameters to the read command (e.g. to wait for a set amount of time).

It uses the read builtin command. This will not detect all key combinations. The output will depend on the terminal used and the character sequences it sends on each key press.

Some special keys are translated into more readable strings: UP, DOWN, RIGHT, LEFT, BACKSPACE, DEL, PAGE_UP, PAGE_DOWN, HOME, END, ESC, F1, ALT+?. However, this is not at all exhaustive and will depend on the terminal used. Use tui::waitForKeyPress if you need to listen to special keys.

This simple implementation does not rely on GNU readline and does not require terminal options to be set using tui::setTerminalOptions.

• $@: read parameters as any: additional parameters to pass to the read command

Returns:

• $?:
  • 0 if a char was retrieved
  • 1 otherwise
• LAST_KEY_PRESSED: the last char (key) retrieved.

tui::waitForChar
tui::waitForChar -t 0.1

https://en.wikipedia.org/wiki/ANSI_escape_code#Terminal_input_sequences

tui::waitForKeyPress

Wait for a key press (single key). You can pass additional parameters to the read command (e.g. to wait for a set amount of time).

It uses the read builtin command with the option -e to use readline behind the scene. This means we can detect more key combinations but all keys needs to be bound first… Special keys (CTRL+, ALT+, F1-F12, arrows, etc.) are intercepted using binding.

You must call tui::rebindKeymap and tui::setTerminalOptions before using this function.

• $@: read parameters as any: additional parameters to pass to the read command

Returns:

• $?:
  • 0 if a key was pressed
  • 1 otherwise
• LAST_KEY_PRESSED: the key pressed.

tui::waitForKeyPress
tui::waitForKeyPress -t 0.1

There are 2 issues when using readline in bash:

1. if the cursor is at the end of the screen, it will make the screen scroll even when nothing is read… Make sure to not position the cursor at the end of the screen.
2. When read is done, it will print a new line in stderr. So we redirect stderr to null. This means that if you print something in a readline bound function, do not print to stderr or you will get nothing !