API v4.0

Breaking changes for API v4.0

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

From 3.4.x to 4.0.x

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

Removed enclosed versions of color sequence properties

Color.cs

public string PlainSequenceEnclosed
public string PlainSequenceEnclosedTrueColor

The plain sequences can already be enclosed in double quotes by escaping them in between the sequences, so these two properties are no longer considered useful. In earlier versions of Nitrocid, they were implemented as a workaround of handling .ini files that were responsible of handling Nitrocid 0.0.4 to 0.0.15 configuration.

We advise you to manually enclose the PlainSequence and/or the PlainSequenceTrueColor properties with double quotes.

Merged various VT sequence tools

VtSequenceTools.cs

public static string FilterVTSequencesMultiple(string Text, string replace = "", VtSequenceType types = VtSequenceType.All)
public static (VtSequenceType, Match[])[] MatchVTSequencesMultiple(string Text, VtSequenceType type = VtSequenceType.All)
public static bool IsMatchVTSequencesMultiple(string Text, VtSequenceType type = VtSequenceType.All)

We've made a refactor of various VT sequence tools in order to be more effective, so we've merged the Single and the Multiple versions together for the above functions in order to make them more efficient. Some of the tools remained unaffected.

We advise you to change how you return the values as appropriate. It's almost exactly the same as the Multiple versions, but without the Multiple prefix.

Removed non-standalone console writer wrappers

ConsoleWrapperTools.cs

public static Action<string, TermReaderSettings> ActionWriteStringNonStandalone
public static Action<string, TermReaderSettings, object[]> ActionWriteParameterizedNonStandalone
public static Action<string, TermReaderSettings> ActionWriteLineStringNonStandalone
public static Action<string, TermReaderSettings, object[]> ActionWriteLineParameterizedNonStandalone

We've finally removed the TermReader-exclusive console writer console wrappers as they were initially never meant to be overridden. It was due to Terminaux's reliance on internal functions in the non-standalone console writer wrapper. It was converted to a simple private function in the reader class.

We advice you to stop overriding the above four wrappers. If you rely on these wrappers, you should change your application code to make better use of Terminaux's tools to avoid having to override the standard wrappers for the terminal reader.

Presentation system overhauled

IElement.cs

bool IsInput { get; }
string? WrittenInput { get; set; }
Action<object[]>? InvokeActionInput { get; }
Action? InvokeAction { get; }

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
public static bool PresentationContainsInput(Slideshow presentation)

Removed elements

public class ChoiceInputElement : IElement
public class InputElement : IElement
public class MaskedInputElement : IElement
public class MultipleChoiceInputElement : IElement

We've overhauled the presentation system by changing how the input is processed. Now, instead of having the input represent an element, we've made a separate interface for them that simplifies the process of adding input to a presentation page and propagating data, called IInputMethod.

Follow the instructions on how to add input to your presentation using this page.

Presentation system now uses the screen feature fully

IElement.cs

void Render();
bool IsPossibleOutOfBounds();

As a result of the breakthroughs that we've done in Terminaux 4.0 compared to the previous series, we've decided to enhance the presentation system by making it fully rely on the screen feature to reduce the number of oddities and bugs that may occur and to reduce the complication and the feel of relying on the presentation dimensions to be able to do things as simple as printing a text.

This is done by removing the IsPossibleOutOfBounds() function and renaming Render() to RenderToString() to reflect its purpose.

Additionally, the presentation system has finally earned the ability to be scrolled as a result of this change!

You should change how you're implementing your element to return a string that represents the element output, as Terminaux now handles all the positioning and the wrapping.

ClearPresentation() removed

PresentationTools.cs

public static string ClearPresentation()

Terminaux now handles clearing the presentation automatically, so your elements can no longer call ClearPresentation().

We advice you to cease using this function. In case of demand, we might bring it back.

Simplified the console color data

ConsoleColorData.cs

public Rgb? RGB
public Hsl? HSL
public class Rgb
public class Hsl

The Hsl property and the class have been removed because it's unnecessary, given that Terminaux already provides the conversion tools. Meanwhile, we've changed the RGB property to return the Terminaux-managed RedGreenBlue class that you can use for many operations, such as conversion. We've also removed the Rgb decoy class.

This is to simplify the console color data by removing extraneous entries from the color data JSON file itself that Terminaux uses to fetch the color data.

If you want to access the HSL info of a console color, you should convert the RGB instance that the RGB property returns using the available conversion tools pinpointed in this page.

Simplified the color blindness formula

TransformationMethod.cs

public enum TransformationMethod

We've decided to separate the color blindness formula class to the following:

• BrettelColorBlind

• VienotColorBlind

As a result, we've implemented three more enumerations clarifying that the three color blindness modes use the Vienot formula. Also, we've removed one argument, method, from the RenderColorBlindnessAware() function.

To continue using the Vienot formula, you must use one of the following formulas as defined in the TransformationFormula enumeration:

• ProtanVienot

• DeutanVienot

• TritanVienot

Updated Textify to migrate the Figletize library

We've merged the Figletize library with the Textify library so that Terminaux can provide more than 550+ Figlet fonts. As a result, we had to update Textify, which means that the Figletize library is no longer installed with Terminaux.

You can consult the breaking change for Textify here.

Removed unlimited input from the reader

TermReaderSettings.cs

public bool LimitConsoleChars

Unlimited input in the multi-line terminal reader was proven to be buggy, and we couldn't find a good solution to the problem, considering all the cases that need to be handled in the terminal reader. We've decided to remove unlimited input from the reader.

If you still want unlimited input, you can use the one-line wrapped reader, which allows unlimited amount of characters.

Slider and progress bar width and height determination changes

SliderColor.cs

public static void WriteSliderPlain(int currPos, int maxPos, int Left, int Top, int WidthOffset, bool DrawBorder = true)
public static void WriteSliderPlain(int currPos, int maxPos, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, bool DrawBorder = true)
public static void WriteSlider(int currPos, int maxPos, int Left, int Top, int WidthOffset, bool DrawBorder = true)
public static void WriteSlider(int currPos, int maxPos, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, bool DrawBorder = true)
public static void WriteSlider(int currPos, int maxPos, int Left, int Top, int WidthOffset, Color SliderColor, bool DrawBorder = true)
public static void WriteSlider(int currPos, int maxPos, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color SliderColor, bool DrawBorder = true)
public static void WriteSlider(int currPos, int maxPos, int Left, int Top, int WidthOffset, Color SliderColor, Color FrameColor, bool DrawBorder = true)
public static void WriteSlider(int currPos, int maxPos, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color SliderColor, Color FrameColor, bool DrawBorder = true)
public static void WriteSlider(int currPos, int maxPos, int Left, int Top, int WidthOffset, Color SliderColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true)
public static void WriteSlider(int currPos, int maxPos, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color SliderColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true)
public static string RenderSliderPlain(int currPos, int maxPos, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, bool DrawBorder = true)
public static string RenderSlider(int currPos, int maxPos, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color SliderColor, bool DrawBorder = true)
public static string RenderSlider(int currPos, int maxPos, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color SliderColor, Color FrameColor, bool DrawBorder = true)
public static string RenderSlider(int currPos, int maxPos, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color SliderColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true)

SliderVerticalColor.cs

public static void WriteVerticalSliderPlain(int currPos, int maxPos, int Left, int Top, int HeightOffset, bool DrawBorder = true)
public static void WriteVerticalSliderPlain(int currPos, int maxPos, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, bool DrawBorder = true)
public static void WriteVerticalSlider(int currPos, int maxPos, int Left, int Top, int HeightOffset, bool DrawBorder = true)
public static void WriteVerticalSlider(int currPos, int maxPos, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, bool DrawBorder = true)
public static void WriteVerticalSlider(int currPos, int maxPos, int Left, int Top, int HeightOffset, Color SliderColor, bool DrawBorder = true)
public static void WriteVerticalSlider(int currPos, int maxPos, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color SliderColor, bool DrawBorder = true)
public static void WriteVerticalSlider(int currPos, int maxPos, int Left, int Top, int HeightOffset, Color SliderColor, Color FrameColor, bool DrawBorder = true)
public static void WriteVerticalSlider(int currPos, int maxPos, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color SliderColor, Color FrameColor, bool DrawBorder = true)
public static void WriteVerticalSlider(int currPos, int maxPos, int Left, int Top, int HeightOffset, Color SliderColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true)
public static void WriteVerticalSlider(int currPos, int maxPos, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color SliderColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true)
public static string RenderVerticalSliderPlain(int currPos, int maxPos, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, bool DrawBorder = true)
public static string RenderVerticalSlider(int currPos, int maxPos, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color SliderColor, bool DrawBorder = true)
public static string RenderVerticalSlider(int currPos, int maxPos, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color SliderColor, Color FrameColor, bool DrawBorder = true)
public static string RenderVerticalSlider(int currPos, int maxPos, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color SliderColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true)

ProgressBarColor.cs

public static void WriteProgressPlain(double Progress, int Left, int Top, int WidthOffset, bool DrawBorder = true, bool Targeted = false)
public static void WriteProgressPlain(double Progress, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, bool DrawBorder = true, bool Targeted = false)
public static void WriteProgress(double Progress, int Left, int Top, int WidthOffset, bool DrawBorder = true, bool Targeted = false)
public static void WriteProgress(double Progress, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, bool DrawBorder = true, bool Targeted = false)
public static void WriteProgress(double Progress, int Left, int Top, int WidthOffset, Color ProgressColor, bool DrawBorder = true, bool Targeted = false)
public static void WriteProgress(double Progress, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color ProgressColor, bool DrawBorder = true, bool Targeted = false)
public static void WriteProgress(double Progress, int Left, int Top, int WidthOffset, Color ProgressColor, Color FrameColor, bool DrawBorder = true, bool Targeted = false)
public static void WriteProgress(double Progress, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color ProgressColor, Color FrameColor, bool DrawBorder = true, bool Targeted = false)
public static void WriteProgress(double Progress, int Left, int Top, int WidthOffset, Color ProgressColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true, bool Targeted = false)
public static void WriteProgress(double Progress, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color ProgressColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true, bool Targeted = false)
public static string RenderProgressPlain(double Progress, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, bool DrawBorder = true, bool Targeted = false)
public static string RenderProgress(double Progress, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color ProgressColor, bool DrawBorder = true, bool Targeted = false)
public static string RenderProgress(double Progress, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color ProgressColor, Color FrameColor, bool DrawBorder = true, bool Targeted = false)
public static string RenderProgress(double Progress, int Left, int Top, int LeftWidthOffset, int RightWidthOffset, Color ProgressColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true, bool Targeted = false)

ProgressBarVerticalColor.cs

public static void WriteVerticalProgressPlain(double Progress, int Left, int Top, int HeightOffset, bool DrawBorder = true)
public static void WriteVerticalProgressPlain(double Progress, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, bool DrawBorder = true)
public static void WriteVerticalProgress(double Progress, int Left, int Top, int HeightOffset, bool DrawBorder = true)
public static void WriteVerticalProgress(double Progress, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, bool DrawBorder = true)
public static void WriteVerticalProgress(double Progress, int Left, int Top, int HeightOffset, Color ProgressColor, bool DrawBorder = true)
public static void WriteVerticalProgress(double Progress, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color ProgressColor, bool DrawBorder = true)
public static void WriteVerticalProgress(double Progress, int Left, int Top, int HeightOffset, Color ProgressColor, Color FrameColor, bool DrawBorder = true)
public static void WriteVerticalProgress(double Progress, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color ProgressColor, Color FrameColor, bool DrawBorder = true)
public static void WriteVerticalProgress(double Progress, int Left, int Top, int HeightOffset, Color ProgressColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true)
public static void WriteVerticalProgress(double Progress, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color ProgressColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true)
public static string RenderVerticalProgressPlain(double Progress, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, bool DrawBorder = true)
public static string RenderVerticalProgress(double Progress, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color ProgressColor, bool DrawBorder = true)
public static string RenderVerticalProgress(double Progress, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color ProgressColor, Color FrameColor, bool DrawBorder = true)
public static string RenderVerticalProgress(double Progress, int Left, int Top, int TopHeightOffset, int BottomHeightOffset, Color ProgressColor, Color FrameColor, Color BackgroundColor, bool DrawBorder = true)

Due to how difficult it was to determine the correct height from the left and the right offsets, we've decided to simplify things by replacing the offset system with the width/height system so that you can immediately determine the width and the height of your slider without having to perform additional calculations. This reduces the need of ConsoleWrapper.Window{Width|Height} call to determine the actual width/height from the two given offsets.

We advise you to revise your slider and/or progress bar calls and change them accordingly to represent the actual width/height.

Merged three custom binding classes

CustomBindings.cs

public static class CustomBindings

The CustomBindings class has been recently expanded to include code from itself and the two internal classes - BindingsReader and BindingsList - that used to include both the binding execution tools and the list of pre-built and custom bindings. For easier maintenance, we've condensed these classes into one, renaming the CustomBindings class to BindingsTools to more accurately reflect its purpose.

None of the functions are affected; just update your reference so that it points to BindingsTools.

History system improvements

TermReaderState.cs

public List<string> History

TermReaderTools.cs

public static void SetHistory(List<string> History)
public static void ClearHistory()

The history system has seen a number of improvements that resulted in it being a standalone component that connects with the terminal reader to make the history function of the reader more powerful than before. As a result, we had to refactor some code, such as making the History property return an array instead of a list.

Instead of directly referencing the two deleted methods from TermReaderTools, you should use the HistoryTools class to manipulate with the history.

Color conversion and parsing tools refactored

Conversion tools

public static class CmykConversionTools
public static class CmyConversionTools
public static class HslConversionTools
public static class HsvConversionTools
public static class RgbConversionTools
public static class RybConversionTools
public static class YiqConversionTools
public static class YuvConversionTools

Parsing tools

public static class CmykParsingTools
public static class CmyParsingTools
public static class HslParsingTools
public static class HsvParsingTools
public static class RgbParsingTools
public static class RybParsingTools
public static class YiqParsingTools
public static class YuvParsingTools

The conversion and the parsing routines have been recently reworked so that all color models have their own base class. This allows dynamic color conversion and easier implementation of the new color models in future Terminaux releases. This is to reduce the number of classes needed for a single color model.

As a result, while the generic parsing and conversion tools are unaffected, we've moved all color model specific tools to their own color model class and overridden the base class methods to use the model specific override instead of the base one that parses all specifiers.

Use the parsing and the conversion tools using the existing classes.

[4.0.0.1] Removed the targeted argument for progress bar

ProgressBarColor.cs

public static void WriteProgress [...] , bool Targeted = false)

We've removed the targeted argument for the horizontal progress bar writers as we've made a breaking change that changes how the slider and the progress bar writers determine the height and the width. To reduce confusion and unexpected results, we've finally removed the targeted argument from all the progress bar writing functions.

It's advised to remove all targeted parameter values and to make appropriate changes.

From 4.0.x to 4.1.x

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

Removed AllowForeground

ColorTools.cs

public static bool AllowForeground

This was made initially to control whether setting foreground colors is allowed or not. However, its implementation had caused several bugs involving foreground colors for advanced rendered objects, such as the selection choices. Therefore, we've removed this property.

Unless you know what you're doing, you should refrain trying to re-implement it. You can, however, use convenience functions that behave similar to this property using the available functions in the ColorTools class.

Replaced border settings with BorderSettings

BorderTools.cs

public static class BorderTools

The BorderSettings class has been introduced to allow you to more comfortably edit the border settings as a way to simplify the process of border customization. Consequently, we have to remove all the char-based overloads from all the supported writers and infoboxes and replace them with the BorderSettings version that simplifies the amount of arguments.

Change your calls to such writers to use the BorderSettings overload.