Boxes

Boxes is a collection of tools for making TUI python projects.

Dependencies

Boxes uses curses, with comes with python, so nothing must be installed additionally

How to use

Setup

First you will have to import the package:

from boxes_tui import TUI

Now you will need to create a new TUI object intance:

my_tui = TUI()

After that you can use the tools that this package supplies.

Curses Wrapper

It is adviced to use the curses wrapper. It supports error handling, in the case your program terminates before calling:

my_tui.cleanup()

To use the wrapper you will have to import:

from curses import wrapper
from boxes_tui import TUI

Change your main function to take in the parameter stdsrc:

def main(srdsrc):

and call it using:

wrapper(main)

You will also need to construct the TUI opject with stdsrc:

my_tui = TUI(stdsrc)

Tool usage

See example.py for a basic TUI script example.

1. Menu

   Creation

   This simple menu is navigatable by arrow keys and enter.

   You have to pass in the lable and a function to execute; all in a list.

   Here is an example for a super basic menu:

   my_menu = tui.Menu(stdscr, [("Hello", tui.nothing), ("Quit", quit_app)])
   

   Here the entrys get stored as a list of tuples of (label, function_to_call)

   As you can see, you also put in a window. Its values (aka the origin coord and the height & width) will be used for the Menu.

   You can chage them later using:

   my_menu.chage_values(x, y, width, height)
   

   Ticking

   Ticking refreshes the menu and processes keypresses. For values it returns, see Returns

   You can tick the function using:

   my_menu.tick(key)
   

   key can be gotten by using:

   key = stdsrc.getch()
   

   Keybinds

   You can set the Menu's keybinds by passing in a keybinds list:

   my_menu = tui.Menu(stdscr, 
                      [("Hello", tui.nothing), ("Quit", quit_app)], 
                      [([curses.KEY_UP, ord("W"), ord("w")], tui.Menu.move_up),
                       ([curses.KEY_DOWN, ord("S"), ord("s")], tui.Menu.move_down),
                       ([10], tui.Menu.select) # (10 = Enter key)
                      ]
                   )
   

   The default keybindings are:

   [
       ([curses.KEY_UP], tui.Menu.move_up),
       ([curses.KEY_DOWN], tui.Menu.move_down),
       ([10, curses.KEY_RIGHT], tui.Menu.select),
       ([curses.KEY_BACKSPACE, curses.KEY_LEFT], tui.Menu.back)
   ]
   

   Returns

   When ticking, the menu may (when the user presses "enter" or "backspace") return a tuple of (index, return_of_the_function)

   Were index is the index of the entry the user selected. -1 if the user pressed backspace.

   return_of_the_function is whatever the function may have returned, that has been called by the menu.

If you encounter any bug, optimization issue or anything else you would like me to change, please feel free to let me know :)