Drivers 2.0

[tznind]

Lets talk about how we might simplify IMainLoop and ConsoleDriver. I firmly believe that it really shouldn't be anywhere near as complicated as it is at the moment.

Relevant issues:

• Adds ANSIDriver - Pure "Console Virtual Terminal Sequences" driver #2940
• Refactoring, cleanup, and abstraction for ConsoleDrivers #3692 (comment)
• Adding a Timeout hammers CPU even when it is not due #3812
• Fixes #2610 - Adds Ansi parser and scheduler. #3791
• Fixes #3767. Allowing any driver to request ANSI escape sequence with immediate response. #3768

Goals:

• 1 CancellationToken to rule them all!
• 0 ManualSlims allowed
• As few Threads as possible
• Maximum reuse of existing core classes e.g. ConcurrentQueue<T>
• No blocking main iteration - ever
• Maximum code reuse between drivers
• Generics
• Drop Key Down / Key Up distinction - we only need KeyPress

Suggested Design

I think we can restrict ourselves to only 2 threads

• Console In
• Everything else (Console Out / Timeouts / Main Loop Logic etc)

Console In

Console In is typically blocking, it needs to run in a Thread because you have to poll for keys. All drivers basically have a variation of the following:

Task.Run (
	() =>
	{
		do
		{
			if (Console.KeyAvailable)
			{
				var key = Console.ReadKey (true);

				// buffer key somewhere
			}

			Task.Delay (50).Wait (ct);
		}
		while (true);
	});

Here are the relevant methods they use and the datatypes they work in. Each driver has its own datatype int or InputRecord but fundamentally its always a sequence of char. Generics should allow us to handle these disperate types consistently without having to duplicate code (see for example AnsiParser<T> in #3791 ).

Driver	Input Datatype	Input Method	Non Blocking Input Check
NetDriver	ConsoleKeyInfo	Console.ReadKey	Console.KeyAvailable
CursesDriver	int	int code = Curses.get_wch(out int wch)	Call Curses.timeout(100); and check code if ERR (no input)
WindowsDriver	InputRecord	ReadConsoleInput	PeekConsoleInput (not currently used by TG)

Main Loop

Similarly to how it is now the main loop should:

// read input buffer
// raise events
// fire timeouts and invokes etc
// layout (if required)
// draw (if required)
// sleep to avoid busywait

The difference is that we should not have any of those steps blocking. There should be no Wakeup method and no EventsPending.

When the Main Loop runs everyone looks at state and does stuff immediately then it reaches the end of its loop and does the only sleeping in the program.

We achieve this with 'state machines' - similar to how things work in video games. Maximum performance - minimum fuss. Also will become super testable as we have abstracted away the variances and split things up into state processing tasks.

[tig]

I'm not ready to give up on keydown/keyup. I want to push terminals to support it over time.

There's not a huge amount of complexity in simulating up.

The rest makes my heart sing... although I haven't read it deeply yet.

[BDisp]

I'm not ready to give up on keydown/keyup. I want to push terminals to support it over time.

Agree. One good situation to use it, is for e.g. to simulate a button down and then up, like the mouse already does. It's a good suggestion that can be implemented 😃

There's not a huge amount of complexity in simulating up.

That true but must be done always in the drivers to leverage the iterations.

The rest makes my heart sing... although I haven't read it deeply yet.

I'm still studying about this. One think I've learning is the advantage of having threads that does all the background work and letting the main UI doing the screen updating, running events, etc.
Having many threads calling Task.Delay isn't very ideal to deal with awaiting, but sometimes it's the only way. That why I like the ManualSlims that really wait without losing performance and it's threading safe. But as I said, I'm still studding about.

[tig]

I have a pretty nifty FSM library I wrote a few years ago in c++. I am fond of FSMs...

[BDisp]

Call Curses.timeout(100); and check code if ERR (no input)

With the big change I'm doing in the #3768 the CursesDriver doesn't depend anymore on get_wch but read a string buffer already with all the ANSI escape sequence at once and if it's reading many may have more than one ANSI escape sequence. That why I created the SplitEscapeRawString method. My idea is to leverage the AnsiEscapeSequenceRequestUtils class to handle and manage all the ANSI escape sequence on all drivers. For NetDriver and CursesDriver this is more feasible. For WindowsDriver needs more careful because all the ANSI escape sequence are always handled on the key down.

[tznind]

Have started scaffolding out what this might look like in this branch: https://github.com/tznind/gui.cs/tree/v2-drivers

I will tackle Net (AKA NetDriver) and Win32 (AKA WindowsDriver). Drawing in existing code as needed but starting from empty.

Success would be a simple exe with just the raw events (mouse location, last click type, recent Ansi responses e.g. DAR and key) output direct to console - probably just with some basic out abstraction like there is here for in.

Then will look to integrate the main Terminal.Gui architecture.

Have added IConsoleOut and started adding implementation details. Test project requires a break point before Stop or it just exits but heres the obligatory hello world:

[tznind]

Got output buffer and console out working enough to put something on the screen

Next step is to process input buffer and get window size etc

using System.Collections.Concurrent;

namespace Terminal.Gui;

public class MainLoop<T> : IMainLoop<T>
{
    public ConcurrentQueue<T> InputBuffer { get; private set; } = new ();

    public IOutputBuffer OutputBuffer { get; private set; } = new OutputBuffer();

    public AnsiResponseParser<T> Parser
    {
        get;
        private set;
    }

    public IConsoleOutput Out { get;private set; }

    /// <inheritdoc />
    public void Initialize (ConcurrentQueue<T> inputBuffer, AnsiResponseParser<T> parser, IConsoleOutput consoleOutput)
    {
        InputBuffer = inputBuffer;
        Parser = parser;
        Out = consoleOutput;
    }


    public void Run (CancellationToken token)
    {
        do
        {
            var dt = DateTime.Now;

            Iteration ();

            var took = DateTime.Now - dt;
            var sleepFor = TimeSpan.FromMilliseconds (50) - took;

            if (sleepFor.Milliseconds > 0)
            {
                Task.Delay (sleepFor, token).Wait (token);
            }
        }
        while (!token.IsCancellationRequested);
    }
    /// <inheritdoc />
    public void Iteration ()
    {
        Random r = new Random ();
        OutputBuffer.SetWindowSize (20, 10);

        OutputBuffer.CurrentAttribute = new Attribute (Color.White, Color.Black);
        OutputBuffer.Move (r.Next(10), r.Next (10));

        // Red
        OutputBuffer.CurrentAttribute = new Attribute (new Color (255, 0, 0), Color.Black);
        OutputBuffer.AddRune ('H');

        // Orange
        OutputBuffer.CurrentAttribute = new Attribute (new Color (255, 165, 0), Color.Black);
        OutputBuffer.AddRune ('e');

        // Yellow
        OutputBuffer.CurrentAttribute = new Attribute (new Color (255, 255, 0), Color.Black);
        OutputBuffer.AddRune ('l');

        // Green
        OutputBuffer.CurrentAttribute = new Attribute (new Color (0, 255, 0), Color.Black);
        OutputBuffer.AddRune ('l');

        // Blue
        OutputBuffer.CurrentAttribute = new Attribute (new Color (100, 100, 255), Color.Black);
        OutputBuffer.AddRune ('o');

        // Indigo
        OutputBuffer.CurrentAttribute = new Attribute (new Color (75, 0, 130), Color.Black);
        OutputBuffer.AddRune (' ');

        // Violet
        OutputBuffer.CurrentAttribute = new Attribute (new Color (238, 130, 238), Color.Black);
        OutputBuffer.AddRune ('W');

        // Red
        OutputBuffer.CurrentAttribute = new Attribute (new Color (255, 0, 0), Color.Black);
        OutputBuffer.AddRune ('o');

        // Orange
        OutputBuffer.CurrentAttribute = new Attribute (new Color (255, 165, 0), Color.Black);
        OutputBuffer.AddRune ('r');

        // Yellow
        OutputBuffer.CurrentAttribute = new Attribute (new Color (255, 255, 0), Color.Black);
        OutputBuffer.AddRune ('l');

        // Green
        OutputBuffer.CurrentAttribute = new Attribute (new Color (0, 255, 0), Color.Black);
        OutputBuffer.AddRune ('d');

        // Blue
        OutputBuffer.CurrentAttribute = new Attribute (new Color (100, 100, 255), Color.Black);
        OutputBuffer.AddRune ('!');


        Out.Write (OutputBuffer);
    }
    /// <inheritdoc />
    public void Dispose ()
    { // TODO release managed resources here
    }
}

[tznind]

I am focusing on 'NetDriver' porting for now. We have parsing and key detection sort of working:

Here is the new class diagram

We have a problem in the sheer number of key / input types we have:

• InputRecord
• ConsoleKey
• ConsoleKeyInfo
• char
• Key
• KeyCode

I think best way to handle this is to make ConsoleKeyMapping the 'god class' of translating. I've started by adding ToChar and ToKey but it is a drop in the water

    public static Key ToKey<T> (T result)
    {
        // TODO: Requires testing
        return result switch
               {
                   ConsoleKeyInfo keyInfo =>MapKey (keyInfo),

                   // TODO: how?
                   // WindowsConsole.InputRecord inputRecord => inputRecord.KeyEvent.UnicodeChar,
                   _ => throw new ArgumentException ($"Unsupported type {typeof (T).Name}")
               };
    }

    public static char ToChar<T> (T result)
    {
        // TODO: Requires testing
        return result switch
               {
                   ConsoleKeyInfo keyInfo => keyInfo.KeyChar,
                   Key key => (char)key,

                   // TODO: probably not that simple
                   WindowsConsole.InputRecord inputRecord => inputRecord.KeyEvent.UnicodeChar,
                   _ => throw new ArgumentException ($"Unsupported type {typeof (T).Name}")
               };
    }

[tig]

I will not cry if the dichotomy between Key and KeyCode goes away..

When I did the Key work, I explicitly decided to NOT take on the task you describe above and left KeyCode in place (although I did rename it from ConsoleKey or whatever it was. I didn't want to have to dive into all the driver logic at that point.

[tznind]

I've added mouse support to AnsiParser and integrated it into v2, here we can see picking up the ansi response sequences for mouse.

Code is massively simplified from DecodeEscSeq to just:

public class MouseParser
{
    // Regex patterns for button press/release, wheel scroll, and mouse position reporting
    private readonly Regex _mouseEventPattern = new (@"\u001b\[<(\d+);(\d+);(\d+)(M|m)", RegexOptions.Compiled);

    /// <summary>
    ///     Parses a mouse ansi escape sequence into a mouse event. Returns null if input
    ///     is not a mouse event or its syntax is not understood.
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    public MouseEventArgs? ProcessMouseInput (string input)
    {
        // Match mouse wheel events first
        Match match = _mouseEventPattern.Match (input);

        if (match.Success)
        {
            int buttonCode = int.Parse (match.Groups [1].Value);
            int x = int.Parse (match.Groups [2].Value);
            int y = int.Parse (match.Groups [3].Value);
            char terminator = match.Groups [4].Value.Single ();

            return new()
            {
                Position = new (x, y),
                Flags = GetFlags (buttonCode, terminator)
            };
        }

        // its some kind of odd mouse event that doesn't follow expected format?
        return null;
    }

    private static MouseFlags GetFlags (int buttonCode, char terminator)
    {
        MouseFlags buttonState = 0;

        switch (buttonCode)
        {
            case 0:
            case 8:
            case 16:
            case 24:
            case 32:
            case 36:
            case 40:
            case 48:
            case 56:
                buttonState = terminator == 'M'
                                  ? MouseFlags.Button1Pressed
                                  : MouseFlags.Button1Released;
[... the rest of this epic switch copied over ...]

[tig]

Brilliant.

Have you seen these?

• Mouse doubleclick stops continous pressed events. #3404
• Mouse API makes it way too hard to track button pressed #3312

It'd be swell if this new work paved the path for fixing those issues. Part of the problem with the current impl, IMO, is the drivers view mouse button events in the wrong way.

[tznind]

Interesting, I will have a look as this develops. At the moment I am trying to get the events as accurately as possible according to what comes in from the raw input streams.

There is a lot of code especially in WindowsDriver to monitor or record 'last statuses' of mouse etc. I haven't tried to move those things in yet. They can always be added in again later as a seperate component 'input massager' or MouseState filter or something.

[tig]

There is a lot of code especially in WindowsDriver to monitor or record 'last statuses' of mouse etc. I haven't tried to move those things in yet. They can always be added in again later as a seperate component 'input massager' or MouseState filter or something.

Yep, I IMO most of it drives the wrong end-user behavior but is overly complex and fragile.