repository·master·Indexed 20 days ago
https://github.com/vladimirmarkelov/cluiA Command Line User Interface library for Go inspired by TurboVision. It provides a variety of terminal-based UI controls including windows, frames, buttons, edit fields, progress bars, and specialized dialogs like FilePicker and LoginDialog. The library features built-in theme support, automatic layout scaling, and a comprehensive set of global and control-specific hotkeys for window manipulation and navigation.
CLUI handles layout automatically based on terminal size and parent constraints. You do not need to set positions manually. Key concepts include:
AutoSize, the library calculates minimal sizes automatically (e.g., a Label's minimal width is based on its text length).Fixed prevents the widget from resizing, forcing it to maintain its minimal size. This is useful for elements like Button.Window elements can overlap each other, a widget cannot overlap another widget.CLUI organizes its UI elements into four distinct categories that define how they behave and how they must be structured in your application:
Window is the only top-level control. It is a visual element that does not have a parent and cannot be a child of another control. Every application must have at least one visible Window. If the last Window is closed, the application terminates. Windows can be modal.Window or another widget; it cannot exist without a parent. Widgets can act as both parents and children.RadioGroup is an invisible control used to manage the selection logic of Radio buttons.Window implementations for common user interactions, such as ConfirmationDialog and SelectDialog.CLUI uses a simplified layout model where any control becomes a container (layout) if it has children. Unlike toolkits like Qt, CLUI does not have dedicated layout objects; instead, the container's direction is determined by its children.
Layouts are strictly linear: controls are arranged either from left to right or from top to bottom in the order they are added. Consequently, a container is always either one control high or one control wide.
Key constraints to remember:
Frame with scale set to 1, then add the target control with scale set to Fixed. This allows the frame to expand with the parent while the control maintains its size and sticks to the edge.// Example of the alignment trick for bottom/right alignment
// 1. Add a frameless Frame with scale 1 (to expand)
// 2. Add the control with scale Fixed (to stay at edge)
container.AddChild(new Frame(..., scale: 1))
container.GetLastChild().AddChild(new MyControl(..., scale: Fixed))Windows are the only controls in CLUI that can be manually moved or resized using a mouse or keyboard.
Hotkeys are executed as key sequences: press the first combination, release it, and then press the second key.
| Action | Hotkey Sequence |
|---|---|
| Resize Window | Ctrl+S followed by an arrow key |
| Move Window | Ctrl+P followed by an arrow key |
| Maximize/Restore | Ctrl+W then Ctrl+M |
| Hide/Move to Background | Ctrl+W then Ctrl+H (moves window to bottom of stack and activates next window) |
TAB key to allow users to move to the next child control using the keyboard.The library uses a scaling coefficient to distribute extra space (Delta) when a container is resized.
Delta = NewSize - StartingSize.Fixed children have a scale of 0).child.Scale * Delta / TotalScaleSize. The remaining Delta is assigned to the last child.Example: If two children both have scale: 1 and the parent size increases by 3, the first child grows by floor(1 * (3 / 2)) = 1, and the second child grows by the remainder: 3 - 1 = 2.
To add CLUI to your Go project, use the go get command to fetch the module from GitHub.
go get -u github.com/VladimirMarkelov/cluiYou can colorize text in widgets like Label, Frame, or ListBox items using HTML-like tags: <Letter:ColorValue>.
Tags:
b: Background colorc, t, f: Text/Foreground color (c is a general color tag)Supported Colors: black, white, green, yellow, blue, magenta, cyan, red, and default (uses the widget's theme color).
Modifiers: bold (or bright), underline (or underlined), and reverse.
Usage Examples:
<t:red bold>: Red, bold text.<t:underline+blue>: Blue, underlined text.<c:green>text<c:>: Resets text color to the widget's default after the word "text".<b:> or <c:>: Shortcuts for resetting background or foreground to default.Colors are temporary and only apply until the end of the string or until another tag is encountered. You do not need to manually reset colors at the end of a string.
"The <c:green>green<c:> text"
"<t:red bold>Warning!<c:>"To use CLUI in your Go application, import the library. It is common practice to use an alias like ui to keep calls concise.
import (
ui "github.com/VladimirMarkelov/clui"
)To create a widget, you must provide a parent container at creation time; otherwise, the widget will be invisible and won't receive messages.
Common arguments for widget creation functions include:
parent: The container the widget belongs to.minimalWidth / minimalHeight: Limits for widget sizes when the parent is resized. Use the constant AutoSize to allow the widget to calculate its own size (e.g., a Label uses its title length) or use library defaults (e.g., Frame defaults to 5x3).title: Text displayed on the widget (not supported by all widgets).scale: Defines how fast the widget grows relative to its siblings when the parent is resized. Use the constant Fixed to prevent resizing.Note: Frame requires an additional argument frameWidth which can be BorderThick or BorderThin.
// Conceptual example of a widget creation signature
CreateWidget(parent, minimalWidth, minimalHeight, title, scale)CLUI must be initialized before creating any controls. ui.InitLibrary() sets up control and theme managers, initializes the underlying termbox library, and prepares the main event loop.
To prevent the terminal cursor from disappearing (which happens because the library turns off the cursor at start), you must call ui.DeinitLibrary() to clean up the terminal before the application exits. Using defer is the recommended way to ensure finalization occurs even if the application logic completes or crashes.
func main() {
ui.InitLibrary()
defer ui.DeinitLibrary()
// ... your other code ...
}