Repository files navigation

A library for creating CUI/TUI interfaces with pre-built widgets in python.

Easily build text-based user interfaces on both Linux and Windows.

py_cui is a python library meant to simplify writing console user interfaces in python. It relies oncurses for terminal rendering, which is traditionally unix-specific, however, you may use thewindows-curses module to runpy_cui on windows.

The main advantagepy_cui has over typical text-based user interface builders is that it relies on widgets and a grid layout manager like most traditional graphical user interfaces. You may define a grid size, and then drop predefined widgets onto it into specific grid locations. Widgets can also be stretched accross multiple grid rows and columns. If you've ever made a Tkinter GUI, you will feel right at home. In addition,py_cui has support for a rich collection of interactive popups such as menus, forms, file dialogs, and more.

If you would like to contribute, feel free to make an issue or pull request after reading through theCONTRIBUTING.md file.

You may installpy_cui via pip (usepip3 if python 2 and 3 are installed side by side)

pip install py-cui

Make sure to run as root/sudo as required. Note that the library is titledpy_cui, but the name of the pypi package ispy-cui, though in most cases, installing with

pip install py_cui

should work OK.

If you would like to usepy_cui directly from source, clone this repository with:

git clone https://github.com/jwlodek/py_cui

Then build/install withpip:

cd py_cuipip install.

If you would like to try it out without installing, first make sure thatcurses is installed (windows-curses if on windows), and then copy one of the example files into the top directory. You may then simply run it withpython3.

Below are some screenshots and gifs of programs written with py_cui. Additional (simpler) examples are available in theexamples/ directory of this repository.

py_cui_2048 is a demo of usingpy_cui to build simple CUI games and applications. The entire game was made in under 400 lines of code.

recoverpy is a utility for recovering files on linux. It will search through every inode to find your requested file block.

pyautogit is the first larger scale project written inpy_cui. Feel free to use it as a guide to programming withpy_cui.

The easiest way to get set up for developing a fullpy_cui application is to use the availablecookiecutter template. First, install thecookiecutter tool:

pip install cookiecutter

Once it is installed, navigate to the directory in which you would like your projects to live, and run:

cookiecutter https://github.com/jwlodek/py_cui_cookiecutter

This will clone the template, and show prompts for several variables, including project name and description, as well as some developer information.Once it is done, you can enter your project directory, install it with pip, and run it, and you should be able to see aHello World example:

cd myprojectpip install.myproject

You are now ready to extend this template for your own application!

Basic usage ofpy_cui starts with creating a PyCUI object, and specifiying it's grid size. Keep in mind that grid cell height and width will be measured in terminal characters, not pixels, so there is a lower limit on legal grid size, and heights will be smaller values than widths. Create this object with:

root=py_cui.PyCUI(7,9)

The above line will create a UI with 7 rows and 9 columns. Then, add widgets with the different add commands:

label=root.add_label('Label Text',0,0)button=root.add_button('Button Text',1,2,column_span=2,command=my_function)...

Finally, start the CUI with

root.start()

py_cui has support for custom key bindings for both the overview mode and focused mode, popup windows and prompts, color rendering rules, and several useful widgets. For more details on writingpy_cui based interfaces, be sure to check on the examples and the documentationhere.

There are some basic rules that apply to allpy_cui based interfaces. There are three key operating modes - overview mode, focus mode, and popup mode.

Overview mode is the main control view of the interface. In this mode you use the arrow keys to move between widgets, and you may select widgets with theEnter key. By default, you may also press buttons in this mode, unlessauto_focus_buttons is set to false when the CUI was created.

When in focus mode, you enter into a particular widget (For example a text box.). Each widget has some predefined basic controls, such as arrow keys to scroll in aScrollMenu. You may also add keybindings to functions for each particular widget. These keybindings will only apply to a widget if it is in focus mode. Enter focus mode by navigating to a widget in overview mode and hitting theEnter key. Return to overview mode from focus mode by pressingEscape.

Popup mode simply displays a popup over the rest of the UI. Each popup type behaves slightly differently. For example, you may exit an info popup mode by pressingSpace,Enter, orEscape, while a loading popup will remain onscreen until whatever operation is being run is terminated.

py_cui unit tests are written forpytest. Make surepytest is installed, and simply run

pytest

in the root directory to run all unit tests.

Below is a table of python projects developed with the help ofpy_cui. If you've made something, feel free to make a pull request to add it!

BSD 3-Clause License

Copyright (c) 2019-2021, Jakub Wlodek