API v3.0

Breaking changes for API v3.0

Here is a list of breaking changes that happened during the API v3.0 period when differing versions of Terminaux introduced breaking changes.

From 2.7.x to 3.0.x

Between the 2.7.x and 3.0.x version range, we've made the following breaking changes:

Console extension separation

ConsoleExtensions.cs

public static class ConsoleExtensions

The console extensions class needed to be separated to several classes to categorize the functions according to their type. This allows easier organization and distinguishing from the common Terminaux console functions from their extensions.

As a result, we've introduced several extensions that you can see here:

Console Extensions

Consult the above page for functions and their categories to migrate from ConsoleExtensions.

Brightness and contrast moved to Transformation.Contrast

Affected classes

namespace Terminaux.Colors

We've moved all the brightness and the contrast classes and enumerations to the Transformation namespace. This is to ensure better organzation. The following classes are affected:

• ColorBrightness

• ColorContrast

• ColorContrastType

You'll have to update your using clauses to Terminaux.Colors.Transformation.Contrast when calling any of these classes.

Moved plain writing functions to TextWriterRaw

TextWriterColor.cs

public static void Write()
public static void WritePlain(string Text, params object[] vars)
public static void WritePlain(string Text, bool Line, params object[] vars)
public static void WritePlain(string Text, TermReaderSettings settings, params object[] vars)
public static void WritePlain(string Text, TermReaderSettings settings, bool Line, params object[] vars)

We've made a breaking change that moves all the raw writing to its own class to reduce confusion. The standard console writer, TextWriterColor, sets the colors regardless of the mode, while the plain writers are more focused on writing console sequences and other raw things to the terminal.

Their names have not been changed, but they have been moved to TextWriterRaw, so you'll need to update the references to these functions to point to that class instead of the TextWriterColor class.

Migrated input functions to TermReader

Input.cs

public static TermReaderSettings GlobalReaderSettings
public static string CurrentMask
public static string ReadLine(bool interruptible = true)
public static string ReadLine(string InputText, bool interruptible = true)
public static string ReadLine(string InputText, string DefaultValue, bool interruptible = true)
public static string ReadLine(string InputText, string DefaultValue, TermReaderSettings settings, bool interruptible = true)
public static string ReadLineWrapped(bool interruptible = true)
public static string ReadLineWrapped(string InputText, bool interruptible = true)
public static string ReadLineWrapped(string InputText, string DefaultValue, bool interruptible = true)
public static string ReadLineWrapped(string InputText, string DefaultValue, TermReaderSettings settings, bool interruptible = true)
public static string ReadLine(string InputText, string DefaultValue, bool OneLineWrap = false, bool interruptible = true)
public static string ReadLine(string InputText, string DefaultValue, bool OneLineWrap = false, TermReaderSettings settings = null, bool interruptible = true)
public static string ReadLineNoInput(bool interruptible = true)
public static string ReadLineNoInput(TermReaderSettings settings, bool interruptible = true)
public static string ReadLineNoInput(char MaskChar, bool interruptible = true)
public static string ReadLineNoInput(char MaskChar, TermReaderSettings settings, bool interruptible = true)

We've discovered that all the ReadLine() functions and their associated properties and function overloads were duplicates of the TermReader's Read() function, so we've decided to migrate them to the TermReader class to avoid inconsistencies for both the application developer and the future versions of Terminaux.

You'll have to refer to the Read() functions found in the TermReader class. You may have to change how to call the function by changing the signatures.

Removed ConsolePlatform

ConsolePlatform.cs

public static class ConsolePlatform

All of its functions have been moved to SpecProbe's Software, so this entire class has been removed.

As Terminaux already makes use of SpecProbe's Software, you should only change the reference to ConsolePlatform to point to PlatformHelper.

Moved RGB value conversion tools

ColorTools.cs

public static double SRGBToLinearRGB(int colorNum)
public static int LinearRGBTosRGB(double linear)

The sRGB and the linear RGB conversion tools have been moved to the transformation tools as they were used for color transformation. They used to be in the ColorTools class, but they were used for color transformation formulas, such as color blindness simulation.

These functions are not affected. You just have to update your references to ColorTools for these functions to point to TransformationTools.

Moved animated writers to DynamicWriters

All affected classes

namespace Terminaux.Writer.ConsoleWriters

The following animated writers have been moved to their own category, DynamicWriters:

• TextWriterSlowColor

• TextWriterWhereSlowColor

• TextWriterWrappedColor

You must update the usings clause to Terminaux.Writer.DynamicWriters to continue using the three above functions.

Removed the Input class

Input.cs

public static class Input
{
    public static (ConsoleKeyInfo result, bool provided) ReadKeyTimeout(bool Intercept, TimeSpan Timeout)
    public static ConsoleKeyInfo DetectKeypress()
}

As the legacy Input class was made empty by the moving the associated Read*() functions to TermReader, we've decided to remove the entire class and move all of the functions to that class.

During the migration, we've renamed DetectKeypress() to ReadKey() and added an overload to determine whether we're intercepting the pressed key. The default value is still true.

If you want to continue using these functions, you'll have to follow the upgrade paths:

• Input.ReadKeyTimeout() -> TermReader.ReadKeyTimeout()

• Input.DetectKeypress() -> TermReader.ReadKey()

Moved the color selector to Inputs

ColorSelector.cs

namespace Terminaux.Colors.Selector

The color selector class, ColorSelector, has been moved from Colors.Selector to Inputs.Styles as it has been considered to be one of the input styles. This makes it for easier organization of the input styles, such as selection and infoboxes.

The class wasn't renamed. You'll have to update the usings clause to use the new namespace.

Interactive TUIs are now generic

BaseInteractiveTui.cs

public class BaseInteractiveTui : IInteractiveTui
public virtual IEnumerable PrimaryDataSource => Array.Empty<string>();
public virtual IEnumerable SecondaryDataSource => Array.Empty<string>();
public static BaseInteractiveTui Instance

IInteractiveTui.cs

public interface IInteractiveTui
public IEnumerable PrimaryDataSource { get; }
public IEnumerable SecondaryDataSource { get; }

InteractiveTuiTools.cs

public static void OpenInteractiveTui(BaseInteractiveTui interactiveTui)
public static void SelectionMovement(BaseInteractiveTui interactiveTui, int pos)

Non-generic IEnumerables tend to be more difficult to work with than the generic ones. Therefore, we've decided to switch to using generic IEnumerables. This means that the interactive TUI interface and the base class have become generic.

As a consequence, you'll have to either provide an exact type that your interactive TUI will work with, such as string or int, or you'll have to use object.

In order to migrate to the new definition, just place a type in both the BaseInteractiveTui and the IInteractiveTui clauses in the beginning of your TUI class. Additionally, place a type in your IEnumerable definition.

Removed InputStyle

InputStyle.cs

public static class InputStyle

To maintain consistency, we've decided to remove the entire class. This is because this class was considered legacy.

You should use printing functions that Terminaux implements with a call to TermReader.Read() instead.

Screen now handles clearing the console

ScreenTools.cs

public static void Render(bool clearScreen = false)
public static void Render(Screen screen, bool clearScreen = false)

Starting from Terminaux 3.0, the clearScreen variable is no longer needed as the screen feature can now figure out when to or not to clear the screen without your screen instance handling it yourself.

However, both local and global configuration will allow you to control whether to enable or to disable automatic handling of clearing the console in some situations where the default clear handler is not feasible enough.

Just remove the clearScreen argument when calling Render().

InputChoiceTools now returns an array of InputChoiceInfo

InputChoiceTools.cs

public static List<InputChoiceInfo> GetInputChoices(string AnswersStr, string[] AnswersTitles)
public static List<InputChoiceInfo> GetInputChoices(string[] Answers, string[] AnswersTitles)

All of the InputChoiceTools, as well as all the input style class functions that use a list of InputChoiceInfo, have their signatures changed to return an array of InputChoiceInfo as this return value is not meant to be modified.

Change all the InputChoiceInfo lists to arrays before using them in the input functions, such as the selection style.

Merged four console blacklists/graylists

TerminalEmulatorBlacklist.cs

public static class TerminalEmulatorBlacklist

TerminalEmulatorGreylist.cs

public static class TerminalEmulatorGreylist

TerminalTypeBlacklist.cs

public static class TerminalTypeBlacklist

TerminalTypeGreylist.cs

public static class TerminalTypeGreylist

We have previously made the blacklist and the graylist for both the terminal types and the terminal emulators. However, each time we need to solve a bug or make an improvement in one of them, we'll have to update all of them to follow suit to avoid inconsistencies in behavior.

As a result, we've merged them to a single class, called ConsoleFilter, that allows you to manage your console filters without any hitch. We've introduced two enums that will be listed in the console checker page.

You'll have to update your references to point to the above class and to make use of both the enums.

Merged TermInfo to the main library

All TermInfo sources

namespace Terminaux.TermInfo

All TermInfo source code has been moved to the main library to make it more powerful. The reasons will be listed under a non-ordered list. This changes all TermInfo classes to the Terminaux.Base.TermInfo namespace.

• The main Terminaux library originally included the TermInfo library as a separate NuGet package before being moved to the Terminaux source code. This caused conflicts as we're trying to move all the TermInfo sources to the main library under Terminaux.Base. We've removed this dependency to maintain consistency and to reduce conflicts.

• The idea that using an original TermInfo.Cli application in a script intended to download an NCurses library source code to extract a single file, called Caps, and to generate source code files under the same application for use with Terminaux's TermInfo is absurd, as users will have to turn on PowerShell script execution manually. Luckily, you can turn on the PowerShell script execution for the process's lifetime. There are Roslyn source generators for this very reason.

• We've maintained the Caps file unmodified from the NCurses 6.4 source code for use with our source generator that generates these files without downloading anything off the Internet except NuGet packages. This ensures faster generation (in case NCurses developers decided to modify the Caps file), especially if your build server is disconnected from the Internet. We're trying to cater to the most general and the most simple build methods possible.

• We've moved the Inspect feature from the original TermInfo.Cli application to our demo application to be able to use it in the form of an interactive TUI. We've also imported all workable terminfo files from the minimal installation of Ubuntu as embedded resources.

• This required us to change the whole Terminaux library to be more nullable-friendly, but we don't currently have plans to make all our libraries nullable-friendly.

However, with respect to the original authors from Spectre.Console's TermInfo, we've decided to preserve the original license file from that project.

None of the functions have been changed. You'll just have to update the namespace imports to point to Terminaux.Base.TermInfo.

As for NCurses, you can consult this page to check to see if there are any newer releases. NCurses doesn't get updated too frequently, and may or may not be updated either annually or bi-annually.

Progress infobox's waitForInput removed

InfoBoxProgressColor.cs

public static void WriteInfoBoxProgress(double progress, string text, bool waitForInput, params object[] vars)
(...)

waitForInput was accidentally added to almost all the progress information box functions. This variable was possibly a leftover from the regular infobox that provides this variable, which tells the informational box to wait for the user input to make it a modal dialog box.

You may have to remove boolean values for this argument. Otherwise, none of the functions have been functionally affected by this change.

Interactive TUI functions now made generic

IInteractiveTUI.cs

public string GetEntryFromItem(object item);
public string GetInfoFromItem(object item);
public void RenderStatus(object item);

BaseInteractiveTui.cs

public virtual string GetEntryFromItem(object item)
public virtual string GetInfoFromItem(object item)
public virtual void RenderStatus(object item)

As a followup to the interactive TUI interface and its associated base class, we've made further modifications to the interactive TUI class by making the three above functions use the generic type instead of relying on the object type. This eliminates all the necessary casting before being able to use the value directly.

You'll have to update your overrides to point to your interactive TUI's data type specified in the beginning of its own class file.

Console color enumeration auto-generated

ConsoleColors.cs

public enum ConsoleColors

To follow-up the migration of the console color data class generation with the internal generator that parses the console color data JSON file from the resources and makes a data class based on it, we've decided to include the ConsoleColors enumeration to the generation process. This causes some of the names to be changed.

The following 4-bit color names have been changed:

• ConsoleColors.DarkYellow -> Olive

• ConsoleColors.Gray -> Silver

• ConsoleColors.DarkGray -> Grey

• ConsoleColors.DarkGreen -> Lime

• ConsoleColors.Magenta -> Fuchsia

• ConsoleColors.Cyan -> Aqua

The rest of the colors that have their names changed now have their own -Alt suffix instead of the color hex as the suffix.

Renamed the color types

ColorType.cs

public enum ColorType
{
    (...)
    _255Color,
    _16Color,
}

To align with our goals for Terminaux 3.0 and to make user experience less confusing, we've decided to rename the two color types to their new names listed below in the hint box.

The following color types have been renamed:

• ColorType._255Color -> EightBitColor

• ColorType._16Color -> FourBitColor

From 3.0.x to 3.2.x

Between the 3.0.x and 3.2.x version range, we've made the following breaking changes:

Reduced input choice complexity

InputChoiceTools.cs

public static InputChoiceInfo[] GetInputChoices(string AnswersStr, string[] AnswersTitles)
public static InputChoiceInfo[] GetInputChoices(string[] Answers, string[] AnswersTitles)

We've reduced the input choice complexity by replacing a string of answers with input choice tuples to make it easier to specify the choices and to reduce the ambiguity with the slash character.

You can fuse the answers and their titles into one tuple array using this function:

public static InputChoiceInfo[] GetInputChoices((string, string)[] Answers)

This is a simple example of how to change the calls to this function:

-var choices = InputChoiceTools.GetInputChoices(["Y", "N", "C"], ["Yes", "No"]);
+var choices = InputChoiceTools.GetInputChoices([("Y", "Yes"), ("N", null), ("C", "Cancel")]);

Removed ConsoleColorsInfo

ConsoleColorsInfo.cs

public class ConsoleColorsInfo : IEquatable<ConsoleColorsInfo>

We've removed this class because it's making things more complicated that it's supposed to be. It's really just a dumbed-down duplicate of ConsoleColorsData which has more than just the RGB values and a property to return the Color instance using this data.

ParsingTools.cs

public static (RedGreenBlue? rgb, ConsoleColorsInfo? cci) ParseSpecifier(string specifier, ColorSettings? settings = null)
public static bool TryParseSpecifier(string specifier, out (RedGreenBlue? rgb, ConsoleColorsInfo? cci) output)
public static (RedGreenBlue rgb, ConsoleColorsInfo cci) ParseSpecifierRgbName(string specifier, ColorSettings? settings = null)
public static bool TryParseSpecifierRgbName(string specifier, out (RedGreenBlue? rgb, ConsoleColorsInfo? cci) output)

As a consequence, the above functions have been changed to no longer return or use this class.

You can no longer use this removed class. If you still rely on it, you'll have to get an instance of ConsoleColorsData for a specific color that you want to analyze.

Obsoleted the length properties for the presentation system

PresentationTools.cs

public static int PresentationUpperBorderLeft
public static int PresentationUpperBorderTop
public static int PresentationUpperInnerBorderLeft
public static int PresentationUpperInnerBorderTop
public static int PresentationLowerInnerBorderLeft
public static int PresentationLowerInnerBorderTop
public static int PresentationInformationalTop

The following presentation properties shown above have been marked as obsolete, because they were initially meant not to be publicly accessible. Due to how the presentation system was implemented, we've made plans to undergo a revamp in a future Terminaux release.

It's recommended to either use the available functions to make your own TUI, or use the built-in interactive TUI functionality as mentioned in its own page until this revamp is done.

The compiler, once you use one of these properties for your custom elements, will issue a warning that says: These were initially reserved for internal use. Also, the presentation system will be revamped in the next few releases.

From 3.2.x to 3.3.x

Between the 3.2.x and 3.3.x version range, we've made the following breaking changes:

Removed overflow check functions from the interactive TUI interface

IInteractiveTui.cs

public List<InteractiveTuiBinding> Bindings { get; set; }
/// <summary>
/// Goes down to the last element upon overflow (caused by remove operation, ...). This applies to the first and the second pane.
/// </summary>
public void LastOnOverflow();
/// <summary>
/// Goes up to the first element upon underflow (caused by remove operation, ...). This applies to the first and the second pane.
/// </summary>
public void FirstOnUnderflow();

We've removed the LastOnOverflow() and the FirstOnUnderflow() functions from the interface so that they can't be overridden anymore. The reason was that because both of these functions usually didn't need to be modified, and the implementation of them was stable. You can still use these functions, but you can't override them.

As an aside, the Bindings property's type has been changed from the generic List of InteractiveTuiBinding objects to the array of these bindings. This ensures that this property can't be modified once declared.

You can no longer override the two above functions. You can also no longer add key bindings on-demand, but we're working to restore it soon once we find ways to better implement it.

Simplified status population

IInteractiveTui.cs

public void RenderStatus(T item);

We've reworked this function to return a string instance that indicates the status. This ensures that you can simplify the status population without manually setting the InteractiveTuiStatus.Status property, which we've internalized its setter as a result of this change.

You need to change the override statement so that it points to GetStatusFromItem(), which is a new function that was implemented as part of this change. You also need to change all the statements that set the InteractiveTuiStatus.Status property so that it returns that status instead, for example:

public override string GetStatusFromItem(string item) =>
    string.IsNullOrEmpty(item) ? "No info." : item;

Internalized some TUI status property setters

InteractiveTuiStatus.cs

public static int FirstPaneCurrentSelection { get; set; } = 1;
public static int SecondPaneCurrentSelection { get; set; } = 1;
public static int CurrentPane { get; set; } = 1;

Before the introduction of SelectionMovement() and SwitchSides(), we've allowed you to set the above three properties that described:

• the one-based first pane current selection,

• the one-based second pane current selection, and

• the one-based current pane

However, setting these properties didn't contain sanity checks, so you had to be cautious when setting these properties.

Starting from Terminaux 3.3.0, we require that you use both SelectionMovement() and SwitchSides() to be able to set these properties as they contain sanity checks. You can no longer use the properties to set them. The SelectionMovement() function, however, requires that you have passed the TUI instance as the first argument, so the easiest way to use it is to just call it with the Instance property inside your interactive TUI code.

Used global password mask settings

TermReader.cs

public static char CurrentMask

This property shown above used to hold the current password mask to pass to the simple password-enabled terminal reader functions so that that mask was used to read the password input. However, the terminal reader settings already declares the current mask character, PasswordMaskChar, so we felt that this property was redundant.

You can no longer use this property, but you can still use the simple password-enabled terminal reader functions. They use the global settings starting from Terminaux 3.3.0 to avoid inconsistency.

From 3.3.x to 3.4.x

Between the 3.3.x and 3.4.x version range, we've made the following breaking changes:

Removed CheckConsoleOnCall

GeneralColorTools.cs

public static class GeneralColorTools

We've removed the GeneralColorTools class which only contained a property that inhibits the console checker for every assembly, called CheckConsoleOnCall. The reason was that because the console checker didn't necessarily have to do with the console colors, although the checker evaluates the console and its capabilities, such as the color support.

We've already added assembly-based workarounds, so we've decided to replace this property with console check whitelists. It's necessary to change your code that depends on the console not being checked to add your assembly to the whitelist.

The easiest way to add your own test assembly to the whitelist is by calling the Assembly.GetEntryAssembly() function within your one-time unit test initialization code.

var asm = Assembly.GetEntryAssembly();
ConsoleChecker.AddToCheckWhitelist(asm);