XtermGUI 0.1.2

Description:

XtermGUI 0.1.2

A lightweight, expressive GUI framework for compatible terminals

Explore the docs »


Getting Started
·
Usage
·
Documentation
·
API
·
License



About the Project
XtermGUI is a lightweight GUI framework for compatible xterm terminals, allowing you to write complex terminal applications, with expressive, concise, and readable code.
With zero external dependencies, and features including keyboard and mouse input, customizable event listeners, and multiple layer management, you can create and manage complex terminal GUIs with minimal overhead, all in Python.

Getting Started
XtermGUI is available on PyPI. To use it in your project, run:
pip install XtermGUI

To install specific previous versions, take a look at the version history, locate the version tag (vX.Y.Z), and run:
pip install Xterm==X.Y.Z


Trouble Shooting
XtermGUI uses xterm-specific control sequences. If XtermGUI is running incorrectly once installed, ensure that the terminal you are using has sufficient mouse-reporting and xterm support support.
This framework has been tested using the default setup for WSL 2 on Windows 10, which uses an xterm-256color terminal by default.
Here is a useful resource for xterm control sequences reference.

Basic Usage
Setting up the terminal
Use the console_inputs context manager to prepare the terminal for use with XtermGUI. This will handle the cleanup automatically.
from xtermgui import console_inputs


with console_inputs():
...

Please note that there may sometimes be control sequence leakage when exiting your application. This is unavoidable (I am yet to find a solution), but will only happen once the application is exited, and for only very short periods of time.
Reading console input
Use the read_console function to read both keyboard and mouse input from the console. View the API summary or documentation for the possible events you can receieve from this function.
from xtermgui import console_inputs, read_console


with console_inputs():
read_key = read_console()
...

Read repeated console input by placing this function in a loop. This can be useful for reading a stream of user inputs.
from xtermgui import console_inputs, read_console


with console_inputs():
while True: # Or some other loop
read_key = read_console()
...

Text Formatting
The Text class can be used to represent formatted text, which can be printed to the console. It provides all the same functionality as the built-in str string type, but can be used in conjunction with the Style and Colour classes to represent coloured and styled text.
from xtermgui import Colours, Styles, Text, Colour, RGBs


Colour.configure_default_background(RGBs.DEFAULT_BACKGROUND_WSL.value) # Test written in WSL, so the background is configured like so


text = "This is styled text."
text_colour = Colours.F_BLUE.value.blend(Colours.F_GREY.value, foreground_bias=0.5, foreground_gamma=2.2) # This blending just uses the default blending parameters
text_background_colour = Colours.B_BLACK.value
text_style = Styles.BOLD.value + Styles.UNDERLINED.value

text = Text(text, colour=text_colour, style=text_style)
text.add_colour(text_background_colour)

print(text) # Prints the text string, with a silver-blue foreground, black background, underlined and in bold


Complex Usage
For more complex use cases, it is best to organise your application using the GUI or LayeredGUI classes. Some of the benefits of this approach are:

Easier & Customizable Event Listeners
Layer Management
Simplified GUI Manipulation

Creating and configuring a GUI
You can create a simple GUI by inheriting from GUI.
from xtermgui import GUI


class MyGUI(GUI):
def __init__(self) -> None:
super().__init__()

You can use this GUI by using the start method as a context manager.
from xtermgui import GUI


class MyGUI(GUI):
def __init__(self) -> None:
super().__init__()


def main() -> None:
gui = MyGUI()

with gui.start():
...


if __name__ == "__main__":
main()

Interactions
Receiving input events, via interactions, is an opt-in behaviour in XtermGUI. When enabled, it handles the input thread automatically, such that all events you receive will be called in a separate thread.
To use a GUI with this capability, pass inputs=True to the start method.
from xtermgui import GUI


class MyGUI(GUI):
def __init__(self) -> None:
super().__init__()


def main() -> None:
gui = MyGUI()

with gui.start(inputs=True):
...


if __name__ == "__main__":
main()

Keyboard Interactions
Receive keyboard events with the KeyboardInteraction decorator.
from xtermgui import GUI, KeyboardInteraction, Events, KeyboardEvent


class MyGUI(GUI):
def __init__(self) -> None:
super().__init__()

@KeyboardInteraction(Events.SPACE.value)
def clicked_space(self, event: KeyboardEvent) -> None:
...

The clicked_space method runs when space is pressed. Reference the API for other keyboard events you can receive.
Mouse Interactions
Mouse events can be dealt with similarly, with the MouseInteraction decorator.
from xtermgui import GUI, MouseInteraction, Events, MouseEvent, Region, Coordinate


INTERACTION_REGION = Region(Coordinate(0, 0), Coordinate(20, 0), Coordinate(20, 10), Coordinate(0, 10)) # An example region - a 20x10 rectangle, which forms a square in the terminal


class MyGUI(GUI):
def __init__(self) -> None:
super().__init__()

@MouseInteraction(Events.LEFT_MOUSE_DOWN.value, region=INTERACTION_REGION) # Runs when left mouse button is pressed within the specified region
def left_mouse_down(self, event: MouseEvent) -> None:
...

Mouse interactions require an Event, and take a Region as an optional argument. If region is omitted, the event will fire at any position.
GUI I/O Operations
The GUI class provides three key I/O methods - print, erase, and clear - each of which are show below.
from xtermgui import GUI, Coordinate


class MyGUI(GUI):
def __init__(self) -> None:
super().__init__()


def main() -> None:
gui = MyGUI()
text = "This text will be printed in the console."
coordinates = Coordinate(10, 5)

with gui.start():
gui.print(text, at=coordinates) # Print provides all the same functionality as the built-in print function
gui.erase(at=coordinates)
gui.clear()


if __name__ == "__main__":
main()

Managing Layers
To manage GUI layers in your application, use the LayeredGUI class. This will provide all of the same I/O methods as the simple GUI class, but manages layers automatically.
from xtermgui import Colour, RGBs, LayeredGUI, Coordinate


Colour.configure_default_background(RGBs.DEFAULT_BACKGROUND_WSL.value)


class MyGUI(LayeredGUI):
def __init__(self) -> None:
super().__init__() # self.base_layer is created automatically
self.second_layer = self.add_layer("Layer Name", z=1) # z-index is the same as that of the existing layer with the greatest z-index by default


def main() -> None:
gui = MyGUI()
text_base_layer = "This text will be printed in the console, on the base layer."
text_1_second_layer = "This text will be printed in the console, on the second layer."
text_2_second_layer = "This text will also be printed in the console, on the second layer."
coordinates = Coordinate(10, 5)

with gui.start():
gui.print(text_base_layer, at=coordinates) # Prints on the active layer by default - this is initially the base layer
gui.print(text_1_second_layer, at=coordinates, layer=gui.second_layer) # Prints over the text on the base layer
with gui.as_active(gui.second_layer): # Second layer is set as active within this scope only
gui.print(text_2_second_layer, at=coordinates) # Overwrites the existing text
gui.clear(layer=gui.second_layer) # Only the content printed to the base layer now shows


if __name__ == "__main__":
main()

Methods on the Layer class should not be used directly - only interact with layered GUIs via the LayeredGUI class methods.
For more examples, functionality, and detail, please refer to the Documentation
API Summary
Details of the XtermGUI API are listed below for quick reference.
Input Events
Input events can be received via the GUI API.
from enum import Enum
from xtermgui import Event, KeyboardEvent, MouseEvent


class Events(Enum):
SHIFT_BACKSPACE: Event = Event("SHIFT_BACKSPACE")
TAB: Event = Event("TAB")
ENTER: Event = Event("ENTER")
BACKSPACE: Event = Event("BACKSPACE")
POUND: Event = Event("POUND")

UP_ARROW: Event = Event("UP_ARROW")
DOWN_ARROW: Event = Event("DOWN_ARROW")
RIGHT_ARROW: Event = Event("RIGHT_ARROW")
LEFT_ARROW: Event = Event("LEFT_ARROW")
END: Event = Event("END")
HOME: Event = Event("HOME")
SHIFT_TAB: Event = Event("SHIFT_TAB")

LEFT_MOUSE_UP: Event = Event("LEFT_MOUSE_UP")
LEFT_MOUSE_DOWN: Event = Event("LEFT_MOUSE_DOWN")
MIDDLE_MOUSE_UP: Event = Event("MIDDLE_MOUSE_UP")
MIDDLE_MOUSE_DOWN: Event = Event("MIDDLE_MOUSE_DOWN")
RIGHT_MOUSE_UP: Event = Event("RIGHT_MOUSE_UP")
RIGHT_MOUSE_DOWN: Event = Event("RIGHT_MOUSE_DOWN")
LEFT_MOUSE_DRAG: Event = Event("LEFT_MOUSE_DRAG")
MIDDLE_MOUSE_DRAG: Event = Event("MIDDLE_MOUSE_DRAG")
RIGHT_MOUSE_DRAG: Event = Event("RIGHT_MOUSE_DRAG")
MOVE: Event = Event("MOVE")
SCROLL_UP: Event = Event("SCROLL_UP")
SCROLL_DOWN: Event = Event("SCROLL_DOWN")

INSERT: Event = Event("INSERT")
DELETE: Event = Event("DELETE")
PAGE_UP: Event = Event("PAGE_UP")
PAGE_DOWN: Event = Event("PAGE_DOWN")
F5: Event = Event("F5")
F6: Event = Event("F6")
F7: Event = Event("F7")
F8: Event = Event("F8")
F9: Event = Event("F9")
F10: Event = Event("F10")
F11: Event = Event("F11")
F12: Event = Event("F12")

F1: Event = Event("F1")
F2: Event = Event("F2")
F3: Event = Event("F3")
F4: Event = Event("F4")
SPACE: Event = Event(" ")
FORWARD_SLASH: Event = Event("/")
BACKSLASH: Event = Event("\\")
VERTICAL_BAR: Event = Event("|")
PIPE: Event = Event("|")
EXCLAMATION_MARK: Event = Event("!")
QUESTION_MARK: Event = Event("?")
COMMA: Event = Event(",")
FULL_STOP: Event = Event(".")
LESS_THAN: Event = Event("<")
LEFT_ANGLE_BRACKET: Event = Event("<")
LEFT_CHEVRON: Event = Event("<")
GREATER_THAN: Event = Event(">")
RIGHT_ANGLE_BRACKET: Event = Event(">")
RIGHT_CHEVRON: Event = Event(">")
SEMI_COLON: Event = Event(";")
COLON: Event = Event(":")
APOSTROPHE: Event = Event("'")
AT: Event = Event("@")
HASHTAG: Event = Event("#")
OCTOTHORPE: Event = Event("#")
TILDE: Event = Event("~")
LEFT_SQUARE_BRACKET: Event = Event("[")
RIGHT_SQUARE_BRACKET: Event = Event("]")
LEFT_CURLY_BRACKET: Event = Event("{")
LEFT_BRACE: Event = Event("{")
RIGHT_CURLY_BRACKET: Event = Event("}")
RIGHT_BRACE: Event = Event("}")
HYPHEN: Event = Event("-")
MINUS: Event = Event("-")
UNDERSCORE: Event = Event("_")
EQUALS: Event = Event("=")
PLUS: Event = Event("+")
BACKTICK: Event = Event("`")
LOGICAL_NEGATION: Event = Event("¬")
BROKEN_BAR: Event = Event("¦")
SPEECH_MARK: Event = Event("\")")
QUOTATION_MARK: Event = Event("\")")
DOLLAR: Event = Event("$")
PERCENT: Event = Event("%")
CARET: Event = Event("^")
AMPERSAND: Event = Event("&")
ASTERISK: Event = Event("*")
LEFT_BRACKET: Event = Event("(")
LEFT_PARENTHESIS: Event = Event("(")
RIGHT_BRACKET: Event = Event(")")
RIGHT_PARENTHESIS: Event = Event(")")

ANY_KEYBOARD: Event = Event(KeyboardEvent.ANY, lambda _: True)
ANY_MOUSE: Event = Event(MouseEvent.ANY, lambda _: True)
UNRECOGNIZED_KEYBOARD: Event = Event(KeyboardEvent.UNRECOGNIZED)
UNRECOGNIZED_MOUSE: Event = Event(MouseEvent.UNRECOGNIZED)

Events that do not appear in this enum (such as the letters of the alphabet) can be created with Event("<LETTER>"). For example, Event("A").
RGB Colours
RGB colours represent only information about a specific colour.
from enum import Enum
from xtermgui import RGB


class RGBs(Enum):
DEFAULT_FOREGROUND = RGB(192, 192, 192)
DEFAULT_BACKGROUND_PYCHARM = RGB(43, 43, 43)
DEFAULT_BACKGROUND_REPLIT = RGB(28, 35, 51)
DEFAULT_BACKGROUND_WSL = RGB(12, 12, 12)
BLACK = RGB(0, 0, 0)
WHITE = RGB(255, 255, 255)
RED = RGB(255, 0, 0)
GREEN = RGB(0, 255, 0)
BLUE = RGB(0, 0, 255)
YELLOW = RGB(255, 255, 0)
CYAN = RGB(0, 255, 255)
MAGENTA = RGB(255, 0, 255)
ORANGE = RGB(255, 165, 0)
PURPLE = RGB(230, 230, 250)
GREY = RGB(142, 142, 142)
BROWN = RGB(162, 162, 42)

Text Colours
Text colours represent the colour of text printed to the console.
from enum import Enum
from xtermgui import Colour, RGBs



class Colours(Enum):
F_BLACK: Colour = Colour(foreground=RGBs.BLACK.value)
F_WHITE: Colour = Colour(foreground=RGBs.WHITE.value)
F_RED: Colour = Colour(foreground=RGBs.RED.value)
F_GREEN: Colour = Colour(foreground=RGBs.GREEN.value)
F_BLUE: Colour = Colour(foreground=RGBs.BLUE.value)
F_YELLOW: Colour = Colour(foreground=RGBs.YELLOW.value)
F_CYAN: Colour = Colour(foreground=RGBs.CYAN.value)
F_MAGENTA: Colour = Colour(foreground=RGBs.MAGENTA.value)
F_ORANGE: Colour = Colour(foreground=RGBs.ORANGE.value)
F_PURPLE: Colour = Colour(foreground=RGBs.PURPLE.value)
F_GREY: Colour = Colour(foreground=RGBs.GREY.value)
F_BROWN: Colour = Colour(foreground=RGBs.BROWN.value)
F_DEFAULT: Colour = Colour(foreground=RGBs.DEFAULT_FOREGROUND.value)

B_BLACK: Colour = Colour(background=RGBs.BLACK.value)
B_WHITE: Colour = Colour(background=RGBs.WHITE.value)
B_RED: Colour = Colour(background=RGBs.RED.value)
B_GREEN: Colour = Colour(background=RGBs.GREEN.value)
B_BLUE: Colour = Colour(background=RGBs.BLUE.value)
B_YELLOW: Colour = Colour(background=RGBs.YELLOW.value)
B_CYAN: Colour = Colour(background=RGBs.CYAN.value)
B_MAGENTA: Colour = Colour(background=RGBs.MAGENTA.value)
B_ORANGE: Colour = Colour(background=RGBs.ORANGE.value)
B_PURPLE: Colour = Colour(background=RGBs.PURPLE.value)
B_GREY: Colour = Colour(background=RGBs.GREY.value)
B_BROWN: Colour = Colour(background=RGBs.BROWN.value)
B_DEFAULT_PYCHARM: Colour = Colour(background=RGBs.DEFAULT_BACKGROUND_PYCHARM.value)
B_DEFAULT_REPLIT: Colour = Colour(background=RGBs.DEFAULT_BACKGROUND_REPLIT.value)
B_DEFAULT_BACKGROUND_WSL = Colour(background=RGBs.DEFAULT_BACKGROUND_WSL.value)

Text Styles
Text styles represent the style of text printed to the console.
from enum import Enum
from xtermgui import Style


class Styles(Enum):
NOT_STYLED: Style = Style()
BOLD: Style = Style(bold=True)
DIMMED: Style = Style(dimmed=True)
ITALIC: Style = Style(italic=True)
UNDERLINED: Style = Style(underlined=True)
HIDDEN: Style = Style(hidden=True)
CROSSED_OUT: Style = Style(crossed_out=True)


License
Distributed under the GNU General Public License v3.0. See LICENSE for further details.
(Back to Top)