Console Themes

Coloring stuff...

Themes consist of color information for each color type. They are made with a simple JSON syntax that's easy to use.

---

Theme structure

In order to make your own theme, you'll have to understand the theme structure and how it gets serialized to the theme object.

Theme JSON structure

Here's the format of each theme JSON file:

{
    "Metadata": {
        "Name": "Theme name",
        "Description": "This is my theme",
        "IsEvent": false,
        "StartMonth": 2,
        "StartDay": 1,
        "EndMonth": 2,
        "EndDay": 22,
        "Calendar": "Gregorian",
        "Category": "Exciting",
        "UseAccentTypes": [
            "LicenseColor",
            (...)
        ],
    },
    "InputColor": "15",
    "LicenseColor": "15",
    "ContKernelErrorColor": "15",
    (...)
}

We'll explain things one by one. The Metadata key consists of some basic information about the theme, like the name and the description. Themes can also be event-based by setting the appropriate property.

Property	Optional	Description
Name		Display name of the theme
Description		Short and concise description of the theme
IsEvent	●	Indicates whether the theme is for a specific event (holidays, celebrations, etc.)
StartMonth	●	The month in which the event starts
StartDay	●	The day in which the event starts
EndMonth	●	The month in which the event ends
EndDay	●	The day in which the event ends
Calendar	●	The calendar to use, such as Hijri, Chinese, etc.
Category	●	The category to use, such as Mesmerizing, Exciting, etc.
UseAccentTypes	●	The color types which the theme management will switch their values with the accent color configurable by the user from the global settings

The following color categories are supported:

Category	Description
Miscellaneous	Themes that don't fit in the available categories
Aesthetic	Aesthetically beautiful themes
Chinese	Themes that are based on the Chinese culture
Exciting	Themes that make you excited
Mesmerizing	Mesmerizing and relaxing themes
Standard	Standard themes (usually housing the first themes ever released)
Linux	Themes that describe the Linux distro logo colors

What follows the metadata is a list of available color types and their color representations using color formats that Colorimetry supports. Your theme files can also support any specifier, as long as the specifier is supported.

Color sequences

Make sure that the event start month and day is earlier than the end month and day. The theme parser will swap the day values and will add a year (end month is bigger than the start) if it detects that the start date is later than the end date (i.e. events can't end before they start).

Theme color types

Terminaux provides you with the following color types to help you make an inspiring theme with nice colors for each type:

Type	Description
Input	Input text
License	License color
HostNameShell	Host name color
UserNameShell	User name color
Background	Background color
NeutralText	Neutral text (for general purposes)
ListEntry	List entry text
ListValue	List value text
Stage	Stage text
Error	Error text
Warning	Warning text
Option	Option text
Banner	Banner text
Question	Question text
Success	Success text
UserDollar	User dollar sign on shell text
Tip	Tip text
SeparatorText	Separator text
Separator	Separator color
ListTitle	List title text
Progress	General progress text
BackOption	Back option text
TableSeparator	Table separator
TableHeader	Table header
TableValue	Table value
SelectedOption	Selected option
AlternativeOption	Alternative option
WeekendDay	Weekend day
EventDay	Event day
TableTitle	Table title
TodayDay	Today
TuiBackground	Interactive TUI background color
TuiForeground	Interactive TUI foreground color
TuiPaneBackground	Interactive TUI pane background color
TuiPaneSeparator	Interactive TUI pane separator color
TuiPaneSelectedSeparator	Interactive TUI pane selected separator color
TuiPaneSelectedItemFore	Interactive TUI pane selected item color (foreground)
TuiPaneSelectedItemBack	Interactive TUI pane selected item color (background)
TuiPaneItemFore	Interactive TUI pane item color (foreground)
TuiPaneItemBack	Interactive TUI pane item color (background)
TuiOptionBackground	Interactive TUI option background color
TuiKeyBindingOption	Interactive TUI key binding in option color
TuiOptionForeground	Interactive TUI option foreground color
TuiBoxBackground	Interactive TUI box background color
TuiBoxForeground	Interactive TUI box foreground color
DisabledOption	Disabled option color
TuiKeyBindingBuiltinBackgroundColor	Interactive TUI builtin key binding background color
TuiKeyBindingBuiltinForegroundColor	Interactive TUI builtin key binding foreground color
TuiKeyBindingBuiltinColor	Interactive TUI builtin key binding color
ProgressFailed	Progress failed text
ProgressPaused	Progress paused text
ProgressWarning	Progress warning text

Custom types

In addition to the above types, the custom types can also be populated in the same way a built-in type would in the theme structure file.

You can use any name as a custom theme color type, and the theme manager will automatically determine what color to use based on a custom type.

---

Theme tools

The kernel theming system provides you with various theme tools that allow you to manage your themes, such as getting the installed themes, setting the theme, and more.

Installing and uninstalling a theme

To install and/or uninstall a theme to the theme manager, use RegisterTheme() and UnregiserTheme().

ThemeTools.cs

public static void RegisterTheme(string theme, ThemeInfo themeInfo) { }
public static void UnregisterTheme(string theme) { }

Getting the installed themes

You can get the installed themes using the two convenience functions:

ThemeTools.cs

public static Dictionary<string, ThemeInfo> GetInstalledThemes() { }
public static Dictionary<string, ThemeInfo> GetInstalledThemesByCategory(ThemeCategory category) { }

The below two functions do the following:

• The first function gets all the installed themes.

• The second function gets all the installed themes by a category.

Getting colors from a theme

You can get all the used colors from either a theme name or a ThemeInfo instance using the two functions:

ThemeTools.cs

public static Dictionary<KernelColorType, Color> GetColorsFromTheme(string theme) { }
public static Dictionary<KernelColorType, Color> GetColorsFromTheme(ThemeInfo themeInfo) { }

Each function does the following:

• The first function gets the theme name and fetches its ThemeInfo instance. Then, it calls the second one.

• The second function gets all the colors from a theme and updates them if there are color types that use the color accent.

Editing a theme

You can edit a theme using a modified ThemeInfo instance to overwrite it with a new theme using EditTheme() that is defined below:

ThemeTools.cs

public static void EditTheme(string theme, ThemeInfo themeInfo) { }

This function replaces an existing theme with the new ThemeInfo instance. This is useful if you want to save changes to the existing theme or override its colors.

Resetting a theme

You can reset a theme using the ResetTheme() function:

ThemeTools.cs

public static void ResetTheme(string theme) { }

This function resets all theme colors to their default settings according to the metadata token that holds initial theme color type definitions.

Using ThemeInfo or GetThemeInfo() to get theme information

To get theme information for a specific theme, you need to use the ThemeInfo constructor. The below constructors can be used:

Constructor	Description
ThemeInfo()	This gives you a new instance of ThemeInfo with the default theme parameters
ThemeInfo(themePath)	This gives you a new instance of ThemeInfo with the theme parameters from the given theme JSON file
ThemeInfo(ThemeFileStream)	This gives you a new instance of ThemeInfo with the theme parameters from the given stream containing the theme JSON contents

Alternatively, you can use GetThemeInfo() to get theme information about a specified theme using the theme name. After that, you can apply a theme using this instance using ApplyTheme.

Checking to see if a theme exists

There is a function that lets you check to see if a theme exists. IsThemeFound() is usable for such themes and can be provided a name of the theme.

ThemeTools.cs

public static bool IsThemeFound(string theme) { }

Theme application

You can also change all your kernel colors so that a theme can be applied using either a theme name, a theme file name, or a ThemeInfo instance using the below functions:

ThemeTools.cs

public static void ApplyThemeFromRegistered(string theme) { }
public static void ApplyThemeFromFile(string ThemeFile) { }
public static void ApplyTheme(ThemeInfo themeInfo) { }
public static void SetColorsTheme(ThemeInfo ThemeInfo) { }
public static bool TrySetColorsTheme(ThemeInfo ThemeInfo) { }

Each function does the following:

• The first function gets a theme name and gets an instance of ThemeInfo for it. Then, it sets the current theme colors to the colors that are defined by a theme.

• The second function parses a theme JSON file while getting an instance of ThemeInfo from it and sets the current theme colors to the colors that are set by that theme.

• The third function gets all the colors from ThemeInfo and sets the current theme colors to the colors that are defined by that instance.

Checking the color requirements

You can also check to see if a theme requires 255 colors or true colors using the below functions:

ThemeTools.cs

// 255 colors
public static bool Is255ColorsRequired(string theme) { }
public static bool Is255ColorsRequired(ThemeInfo theme) { }
public static bool Is255ColorsRequired(Dictionary<KernelColorType, Color> colors) { }

// True colors
public static bool IsTrueColorRequired(string theme) { }
public static bool IsTrueColorRequired(ThemeInfo theme) { }
public static bool IsTrueColorRequired(Dictionary<KernelColorType, Color> colors) { }

Each function takes either a theme name, an instance of ThemeInfo, or a dictionary of each kernel color type with their color instance.

• The 255-color requirement functions check the Color instance for the type and return true if the type is 255 colors. Also, they return true if the theme requires true colors.

• The true color requirement functions check the Color instance for the type and return true if the type is true colors.

Getting and setting theme colors

You can get and set theme colors individually from the ThemeInfo instance using a specific type as an argument. Getting colors from a theme can be achieved using the GetColor() function, and setting colors in a theme can be achieved using the SetColor() function.

ThemeInfo.cs

public Color GetColor(ThemeColorType type) { }
public Color GetColor(string type) { }
public void SetColor(ThemeColorType type, Color color) { }
public void SetColor(string type, Color color) { }

Each function takes either a named theme color type or an enumerated type that is of type ThemeColorType to specify what theme color type you want to get the color from. The SetColor() functions require that the color be specified.

Converting colors

Your theme files can also support any specifier, as long as the specifier is supported by Colorimetry. You can consult the page below:

---

Theme preview tools

In addition to the theme tools, you can also access the theme preview tools using the ThemePreviewTools class. Currently, the theme preview tools provides you two types of theme preview:

Simple preview

The simple theme preview shows you a wrapped list of color types and their examples, colored with the foreground color in the placeholder text. You can get access to this preview by calling these functions:

ThemePreviewTools.cs

public static void PreviewThemeSimple(string theme)  { }
public static void PreviewThemeSimple(ThemeInfo theme) { }

Each of these two functions get a list of color types known by the color management tools and their associated colors. Then, they show you a preview of the theme colors.

Interactive preview

The interactive theme preview shows you a full-screen colored box that changes its color according to the selected color type and the list of theme colors. You can get access to this preview by calling these functions:

ThemePreviewTools.cs

public static void PreviewTheme(string theme) { }
public static void PreviewTheme(ThemeInfo theme) { }

Each of these two functions get a list of kernel color types known by the color management tools and their associated colors. Then, they show you a preview of the theme colors.