From e38456adebb2c3682fd569884e5807f5fead6a5d Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Mon, 31 Oct 2022 20:27:21 +0100 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 1 + THEMES-DEV.md | 122 ++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 90 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b46f8d9c..38e74102a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ * Made fundamental changes to the application logic by removing most view styles and replacing them with a new theme variants concept * Added theme support for defining and applying different layouts for various display aspect ratios such as 16:9 and 4:3 +* Added theme support for defining and applying different color schemes * Made gamelist theming much more flexible by allowing any number of elements of any types to be defined * Deprecated multiple older theming concepts like features, extras and hardcoded metadata attributes * Renamed the default theme set from rbsimple-DE to slate-DE diff --git a/THEMES-DEV.md b/THEMES-DEV.md index 0c3b0e1cc..d490375a7 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -68,9 +68,9 @@ In the past EmulationStation basically had hardcoded view styles with certain el With the new theme engine the view presets were removed and the only views now available, _system_ and _gamelist_, were rewritten to be much more flexible. Essentially the element selection and placement is now unlimited; any number of elements of any type can be used, although with a few notable exceptions as explained throughout this document. -In addition to the variant support which provides an unlimited flexibility for creating custom theme profiles, support for specific aspect ratios was introduced. This makes it possible to define different theme configuration for different display aspect ratios and to provide the user with the option to choose between these from the _UI Settings_ menu. That could for example be choice between a 16:9 and a 4:3 layout, or perhaps also a vertical screen orientation layout in addition to these. +In addition to _variants_, support for _color schemes_ and _aspect ratios_ was introduced. The former makes it possible to provide different color profiles via variable declarations, and the latter makes it possible to define different theme configurations for different display aspect ratios. That could for example be a choice between a 16:9 and a 4:3 layout, and perhaps also a vertical screen orientation layout. All these options are selectable via the _UI Settings_ menu. -As well new theming abilities like GIF and Lottie animations were added with the new theme engine. +New theming abilities like GIF and Lottie animations were also added to the new theme engine. The following are the most important changes compared to the legacy theme structure: @@ -285,11 +285,11 @@ Here are some example uses of the `` functionality: ```xml - - ./../colors_light.xml + + ./gamelist_textlist.xml - - ./../colors_dark.xml + + ./gamelist_carousel.xml @@ -311,17 +311,7 @@ Here are some example uses of the `` functionality: ```xml - - - - titlescreen - true - 42 - - - - - + + + + + titlescreen + true + 42 + + + @@ -346,16 +345,64 @@ Here are some example uses of the `` functionality: ``` +## Color schemes + +Color schemes are essentially a collection of variables that can be selected between from the _UI Settings_ menu. This makes it possible to define different values that will be applied to the overall theme configuration based on this menu selection. Only variables can be used for the color schemes, but since variables can be used for almost everything this makes the functionality very flexible. In most cases you'll probably want to apply different color values to `` properties and similar, but it's also possible to apply different images, animations, fonts etc. per color scheme. + +To understand the basics on how to use variables, make sure to read the _Theme variables_ section elsewhere in this document. + +Before a color scheme can be used it needs to be declared, which is done in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detail later in this document. + +Each `` tag pair must be placed inside the `` tag pair - it can only be used on this level of the hierarchy. + +The mandatory name attribute is used to specificy which color scheme to use, and multiple values can be specified at the same time by separating them by commas or by whitespace characters (tabs, spaces or line breaks). + +Note that the use of color schemes for a theme set is entirely optional. + +Here's an example configuration: + +```xml + + + + 404040 + F0F0F0 + + + + + + 707070 + 262626 + + + + + + + 0 0 + 1 1 + ./core/images/background.png + true + ${backgroundColor} + + + 0.5 0.6437 + 1 0.056 + ${defaultTextColor} + + + + +``` ## Aspect ratios -The aspect ratio support works almost identically to the variants support with the main difference that the available aspect ratios are hardcoded into ES-DE. The theme set can still decide which of the aspect ratios to support (or none at all in which cast the theme aspect ratios is left undefined) but it can't create entirely new aspect ratios. +The aspect ratio support works almost identically to the variants and color schemes with the main difference that the available aspect ratios are hardcoded into ES-DE. The theme set can still decide which of the aspect ratios to support (or none at all in which case the theme aspect ratio is left undefined) but it can't create entirely new aspect ratio entries. -The reason for why aspect ratios were implemented at all instead of only using variants was that the amount of defined variants would have grown exponentially for all possible combinations, making the theme sets very hard to create and maintain. +In the same manner as for the variants and color schemes, the aspect ratios that the theme set provides need to be declared in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detailed later in this document. -In the same manner as for the variants, the aspect ratios that the theme set provides need to be declared in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detailed later in this document. - -Once the aspect ratios have been defined, they are applied to the theme configuration in exactly the same way as the variants: +Once the aspect ratios have been defined, they are applied to the theme configuration like the following: ```xml @@ -411,14 +458,14 @@ Once the aspect ratios have been defined, they are applied to the theme configur ## capabilities.xml -Variant and aspect ratio values need to be declared before they can be used inside the actual theme set configuration files and that is done in the `capabilities.xml` file. This file needs to exist in the root of the theme directory, for example: +Variants, color schemes and aspect ratios need to be declared before they can be used inside the actual theme set configuration files and that is done in the `capabilities.xml` file. This file needs to exist in the root of the theme directory, for example: ``` ~/.emulationstation/themes/mythemeset-DE/capabilities.xml ``` This file type was introduced with the new ES-DE theme engine in v2.0 and is an indicator that the theme set is of the new generation instead of being of the legacy type (i.e. a theme set backward compatible with RetroPie EmulationStation). In other words, if the capabilities.xml file is absent, the theme will get loaded as a legacy set. -The structure of the file is simple, it just contains the declarations for the variants and aspect ratios, such as in this example: +The structure of the file is simple, it just contains declarations for the variants, color schemes and aspect ratios, such as in this example: ```xml @@ -427,22 +474,30 @@ The structure of the file is simple, it just contains the declarations for the v 4:3 4:3_vertical - + + + + + + + + + true - - + + true ``` -The file format is hopefully mostly self-explanatory; this example provides three aspect ratios and two variants. The `