pavkam / sharpie

Terminal manipulation library based on Curses (ncurses, pdcurses and pdcurses-mod) for modern .NET applications.

Sharpie

Sharpie is a terminal manipulation library based on NCurses and targeting .NET 6 (dotnet core) and above.

Or, if you prefer the Snake game...

Platforms

Sharpie supports any platform that .NET 6.0+, ncurses, pdcurses and pdcurses-mod support. This essentially means that Linux, Macos and Windows are supported on both x64 and ARM64 architectures.

For more information on supported platforms visit .NET Supported Platforms Page and NCurses Packages Page.

Sharpie provides unofficial builds for all the supported libraries located in the lib directory

Installation

Install the main library by adding the NuGet package:

dotnet add package Sharpie-Curses

Additionally, one can install packages containing prebuilt native libraries. These packages are useful when targeting platforms that do not bundle a supported curses library by default (e.g. Windows).

dotnet add package Sharpie-Libs-PdCurses
dotnet add package Sharpie-Libs-PdCursesMod
dotnet add package Sharpie-Libs-NCurses

Features

Almost all of Curses functionality is exposed through Sharpie. What follows is a list of suppoerted features:

1. Terminal allows interfacing with terminal functionality exposed by Curses,
2. Screen abstracts away the screen handling,
3. Pad abstracts away the off-screen windows (known as pads),
4. SubPad and SubWindow carves out areas of their respective parents for easy management,
5. EventPump allows developers to listen for Curses events such as key presses, mouse moves and resizes,
6. ColorManager abstracts away the management of colors,
7. Even SoftLabelKeys are supported (though antiquated),

In addition to wrapping NCurses, this library also adds numerous quality-of-life improvements such as:

1. Management of overlapping Windows within a Screen,
2. Proper Window resizing and placement during terminal resizing events,
3. Automatic Screen refresh management and support for atomic refreshes,
4. Supports SynchronizationContext-type execution,
5. Supports protected/synchronized or raw access to all classes,
6. And other small additions here and there...

Reasons

There are a number of libraries out there that already offer bindings to NCurses. One of the more popular one is Terminal.Gui; and others such as dotnet-curses also exist.

So why another one? The are many reasons, but the most important ones are:

1. There is no .NET, object-oriented version of NCurses bindings,
2. Existing versions are old, or are targeting old versions of .NET which do not benefit from numerous advances in the .NET platform,
3. No other library exposes most of Curses functionality,
4. Testing is either very limited or completely non-existent.
5. And finally -- because I wanted to dabble in Curses.

How To

What follows is a small example of how to use the library:

// Create the terminal instance without any non-standard settings.
using var terminal = new Terminal(CursesBackend.Load(), new(ManagedWindows: true));

// Set the main screen attributes for text and drawings.
terminal.Screen.ColorMixture = terminal.Colors.MixColors(StandardColor.Green, StandardColor.Blue);

// Draw a border on the screen.
terminal.Screen.DrawBorder();

// Force a refresh so that all drawings will be actually pushed to teh screen.
terminal.Screen.Refresh();

// Create a child window within the terminal to operate within.
// The other cells contain the border so we don't want to overwrite those.
var subWindow = terminal.Screen.SubWindow(
    new(1, 1, terminal.Screen.Size.Width - 2, terminal.Screen.Size.Height - 2));

// Process all events coming from the terminal.
foreach (var @event in terminal.Events.Listen(subWindow))
{
    // Write the  event that occured.
    subWindow.WriteText($"{@event}\n");
    
    // If the event is a resize, change the size of the child window
    // to allow for the screen to maintain its border.
    // And then redraw the border of the main screen.
    if (@event is TerminalResizeEvent re)
    {
        subWindow.Size = new(re.Size.Width - 2, re.Size.Height - 2);
        terminal.Screen.DrawBorder();
    }
    
    // If the user pressed CTRL+C, break the loop.
    if (@event is KeyEvent { Key: Key.Character, Char.IsAscii: true, Char.Value: 'C', Modifiers: ModifierKey.Ctrl })
    {
        break;
    }
}

As you can imagine, there are numerous other uses built into the library. Start out by reading Setting Up The Terminal wiki page.

sharpie's Issues

Mouse event processing is broken when ripoffline is used

Windows: add loader code to look up for local "libncursesw6.dll"

• libncursesw[Major.Minor].dll
• libncursesw[Major].dll
• libncursesw.dll
• Maybe without "w" suffix as well.

SoftKeys

Hi, nice library! I was testing out the demos in your repo, and I can't seem to get SoftKeys to work, unless I use PdCursesMod, which in it's turn seem to have issues with the font in Visual Studio 2022 Dev Console (garbled characters and refresh issues as far as I can tell). PdCurses works fine and all demos do work without issues, just the slk demo that is problematic. So i guess my question is, is Softkeys only supported in PdCursesMod or is it supposed to be working in PdCurses and Ncurses as well?

Here's the error that's thrown:
Sharpie.CursesOperationException: 'The call to slk_init failed: Failed to initialize soft label keys.'

Windows: setting cursor fails

Do not fail if setting the cursor fails during setup.

Windows: setting default colors fails

Adjust the code that uses -1 for the default color to understand not to use it if it would fail. Default to White/Black for those cases.

Find a better way of deling with zero Width/Height sizes (instead of crashing)

if (!Screen.Size.AdjustToActualArea(ref area))
{
    throw new ArgumentOutOfRangeException(nameof(value));
}