Home

Context

looks.py is a lightweight terminal-based UI framework built with Python’s curses library. It provides a simple way to create interactive text-based applications with windows, buttons, scrolling, and background services.

📦 Installation

Clone or download the repository containing looks.py. Make sure you are using Python 3 with curses installed (already available by default on Linux/macOS; on Windows you may need windows-curses):

pip install windows-curses   # Only if on Windows

🚀 Getting Started

1.Import the framework

from looks import app

2. Define a background service

The service runs in a separate thread, receiving input events and updating the UI content.

def appService(app_front):
    while True:
        if app_front.key_inputs:
            key = app_front.key_inputs.pop(0)
            if key == curses.KEY_CLOSE:   # Close window
                break
        # update content, scroll, etc.

The app_front object (an instance of app) exposes:

content → List of strings shown in the UI.
key_inputs → Captures user keystrokes and button presses.
scrolldown() → Scrolls view to the bottom.
get_current_size() → Returns terminal window size.

3. Add buttons

Buttons are defined as a list of tuples (label, handler_function). Each button appears in the top-right corner of the UI.

def onScroll():
    myApp.content.append("Scroll clicked!")

def onPause():
    myApp.key_inputs.append(curses.KEY_BACKSPACE)

myApp = app(
    "My App Title",
    appService,
    buttons=[("S", onScroll), ("P", onPause)]
)

4. Launch the application

Call activate() to start the UI loop:

myApp.activate()

📖 Example (test.py)

Here’s a working demo that streams lines from a text file:

import curses
import time
from looks import app

# Load sample text
with open("random_text_file.txt", "r") as f:
    lines = f.read().splitlines()

def appService(app_front):
    play = True
    while True:
        if app_front.key_inputs:
            key = app_front.key_inputs.pop(0)
            if key == curses.KEY_CLOSE:
                break
            if key == curses.KEY_BACKSPACE:
                play = not play   # toggle play/pause
        
        if lines:
            if play:
                app_front.content.append(lines.pop(0))
                app_front.scrolldown()
                time.sleep(1)
        else:
            break

def scrollBtn():
    myApp.content.append(str(myApp.get_current_size()))

def pauseBtn():
    myApp.key_inputs.append(curses.KEY_BACKSPACE)

myApp = app(
    "Text Reader",
    appService,
    buttons=[("S", scrollBtn), ("P", pauseBtn)]
)

myApp.activate()

Run it:

python test.py

You will see a terminal UI with:

Text output streaming line by line.
[X] button to close.
[S] button to log window size.
[P] button to pause/resume streaming.

⌨️ Keyboard & Mouse Controls

Mouse click on [X] → Exit app.
Mouse click on other buttons → Run their handlers.
Keyboard input → Captured in app_front.key_inputs.
Window resize → UI redraws automatically.

🛠 Tips

Keep content as a list of strings; new lines will automatically scroll.
Handle errors inside your service gracefully—exceptions are caught and printed after exit.
Use curses constants like curses.KEY_BACKSPACE, curses.KEY_RESIZE, etc.

Navigation Menu