BeautifulConsole 0.2.0

BeautifulConsole

A powerful .NET library for building beautiful console applications with true‑color support, cross‑platform clipboard, advanced window customization, and a clean, black‑box API.

dotnet add package BeautifulConsole

• Package: nuget.org/packages/BeautifulConsole
• Version: 0.2 | .NET 6+
• Developer: Lonewolf239

Features

Installation

dotnet add package BeautifulConsole

Quick Start

Hello, World! with color

using BeautifulConsole;
using BeautifulConsole.Models; // For Message class

BConsole.WriteLine(new Message("Hello, BeautifulConsole!", Color.NeonGreen));
BConsole.WriteLine(new Message("This is red on cyan", Color.Red, Color.Cyan));

Read input with a prompt

string name = BConsole.ReadLine(new Message("What is your name? ", Color.Yellow));
BConsole.WriteLine($"Hello, {name}!", Color.Yellow);

Gradient text

BConsole.WriteGradient("This text flows from red to blue", Color.Red, Color.Blue);

Configure the console window (Windows)

var options = new BOptions
{
    Title = "My App",
    Width = 100,
    Height = 30,
    CenterWindow = true,
    DisableCloseButton = true,
    CursorSize = 50
};

BConsole.SetupConsoleSettings(options);

Copy text to clipboard

BeautifulConsole.Clipboard.Clipboard.SetText("Hello from BeautifulConsole!");
string text = BeautifulConsole.Clipboard.Clipboard.GetText();
if (BeautifulConsole.Clipboard.Clipboard.IsTextAvailable())
    Console.WriteLine($"Clipboard contains: {text}");

Ensure single instance

if (!BConsole.SetMutex("MyApp_Unique_Name"))
{
    Console.WriteLine("Another instance is already running.");
    return;
}
// Your app logic...
// When done, call BConsole.ReleaseMutex() or let the finalizer handle it.

Detailed Usage

Colored Output

All Write and WriteLine methods accept a Message object that can contain text and optional foreground/background colors:

• Write(Message? message)
• WriteLine()
• WriteLine(Message? message)

Example:

BConsole.WriteLine(new Message("This is green text", Color.Green));
BConsole.WriteLine(new Message("White on blue", Color.White, Color.Blue));

The AutoResetColor property (default true) automatically returns to the default colors after each output. Set it to false if you want colors to persist:

BConsole.AutoResetColor = false;
BConsole.Write(new Message("This stays ", Color.Red));
BConsole.WriteLine(new Message("red", Color.Red));
BConsole.ResetColor();   // manual reset

Default colors can be changed:

BConsole.DefaultForegroundColor = Color.LightGray;
BConsole.DefaultBackgroundColor = Color.DarkBlue;

Gradient Text

The WriteGradient method writes text with a smooth color transition:

WriteGradient(string text, Color startColor, Color endColor, bool resetAfter = true);

Example:

BConsole.WriteGradient("Rainbow effect", Color.Red, Color.Violet);

Input with Prompts

All input methods have overloads that display a colored Message before reading:

• Read(bool newLine)
• Read(Message? message, bool newLine)
• ReadLine(bool newLine)
• ReadLine(Message? message, bool newLine)
• ReadKey(bool intercept, bool newLine)
• ReadKey(bool intercept, Message? message, bool newLine)

Example:

var prompt = new Message("Enter your name: ", Color.Cyan);
string name = BConsole.ReadLine(prompt);
BConsole.WriteLine($"Hello, {name}!");

Console Window Configuration

The BOptions class provides extensive control over the console window (Windows only for most features; some settings like size and title work cross‑platform).

Additionally, many console properties are now directly accessible via BConsole:

• CursorVisible
• WindowWidth, WindowHeight
• BufferWidth, BufferHeight
• Title
• TreatControlCAsInput
• CursorSize
• NumberLock, CapsLock (Windows only)
• LargestWindowWidth, LargestWindowHeight
• IsInputRedirected, IsOutputRedirected, IsErrorRedirected
• InputEncoding, OutputEncoding

Mouse Support (Experimental)

You can enable or disable mouse event reporting in terminals that support it:

BConsole.EnableMouse();  // Start receiving mouse events
BConsole.DisableMouse(); // Stop receiving mouse events

Note: Mouse event handling is not yet fully implemented – only the enabling/disabling of reporting is supported. Future versions will add event reading and processing.

Clipboard Operations

The BeautifulConsole.Clipboard.Clipboard static class provides a simple clipboard API:

• void SetText(string? text)
• bool TrySetText(string? text) – returns success status without throwing.
• string? GetText()
• bool IsTextAvailable()
• bool Clear()

Platform notes:

• Windows: Uses WinAPI (user32.dll).
• macOS: Uses pbcopy/pbpaste (must be installed by default).
• Linux: Uses wl-copy (Wayland) or xclip/xsel (X11). The library automatically detects available tools.

Color Utilities

The Color class provides over 150 predefined colors. You can also create custom RGB colors:

Color custom = new Color(123, 45, 67);
BConsole.WriteLine(new Message("Custom color", custom));

Predefined colors include:

• Basic: Color.Red, Color.Green, Color.Blue, Color.White, Color.Black
• Web: Color.AliceBlue, Color.AntiqueWhite, Color.Cornsilk, etc.
• Pastel: Color.PastelRed, Color.PastelGreen, Color.PastelBlue
• Neon: Color.NeonRed, Color.NeonGreen, Color.NeonBlue
• Metallic: Color.GoldMetallic, Color.SilverMetallic, Color.Bronze
• Earth tones: Color.Earth, Color.Clay, Color.Sand, Color.Moss

All colors are immutable and thread‑safe.

API Reference

A quick overview of the public API:

BConsole (static class)

Output

• Write(Message? message)
• WriteLine()
• WriteLine(Message? message)
• WriteGradient(string text, Color startColor, Color endColor, bool resetAfter = true)
• Clear()
• ResetColor()

Input

• Read(bool newLine = false)
• Read(Message? message, bool newLine = false)
• ReadLine(bool newLine = false)
• ReadLine(Message? message, bool newLine = false)
• ReadKey(bool intercept = false, bool newLine = false)
• ReadKey(bool intercept, Message? message, bool newLine = false)

Properties

• bool AutoResetColor { get; set; }
• Color DefaultForegroundColor { get; set; }
• Color DefaultBackgroundColor { get; set; }
• bool CursorVisible { get; set; }
• int WindowWidth { get; set; } (Windows only for setter)
• int WindowHeight { get; set; } (Windows only for setter)
• int BufferWidth { get; set; } (Windows only for setter)
• int BufferHeight { get; set; } (Windows only for setter)
• string Title { get; set; }
• bool TreatControlCAsInput { get; set; }
• int CursorSize { get; set; }
• bool NumberLock { get; } (Windows only)
• bool CapsLock { get; } (Windows only)
• int LargestWindowWidth { get; }
• int LargestWindowHeight { get; }
• bool IsInputRedirected { get; }
• bool IsOutputRedirected { get; }
• bool IsErrorRedirected { get; }
• Encoding InputEncoding { get; set; }
• Encoding OutputEncoding { get; set; }

Setup & Single Instance

• void SetupConsoleSettings(BOptions? options)
• bool SetMutex(string? mutexName)
• void ReleaseMutex()

Mouse

• void EnableMouse()
• void DisableMouse()

BOptions (class)

All properties are nullable or have sensible defaults. See the Console Window Configuration section for a complete list.

Color (class)

• Constructors: Color(int r, int g, int b), Color() (empty color)
• Over 150 static predefined colors.
• Properties: R, G, B (bytes).
• Methods: Blend, Gradient, ToHsl, FromHsl, ToHsv, FromHsv, ToXterm256Index.

Message (class)

• Message(string? text, Color? foreground = null, Color? background = null)
• Message(char text, Color? foreground = null, Color? background = null)
• Properties: Text, ForegroundColor, BackgroundColor.

Clipboard (static class, accessible via BeautifulConsole.Clipboard.Clipboard)

• void SetText(string? text)
• bool TrySetText(string? text)
• string? GetText()
• bool IsTextAvailable()
• bool Clear()

Philosophy

Black Box Design – all internal logic is hidden behind the simple, static BConsole API. You interact with clean methods and properties without worrying about ANSI escape sequences, platform differences, or internal state management. BeautifulConsole manages everything for you.