From 370adbb36944003e4242f3a609ab6eb5a21784f4 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Sun, 8 Jan 2023 20:55:34 +0100 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 2 ++ THEMES-DEV.md | 87 ++++++++++++++++++++++++++++++++++++++++++++---- USERGUIDE-DEV.md | 8 +++-- 3 files changed, 89 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fd4b1c8fd..a6bdb4be9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,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 +* Added theme support for defining and applying granular transition animation profiles * Added a new grid component that is usable in both the system and gamelist views * 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 @@ -189,6 +190,7 @@ * When building as an AppImage a current SDL library release is now built and bundled instead of including the OS-supplied version * When building as an AppImage the "data" directory (e.g. /usr/share/emulationstation) is now excluded when looking for resources and themes * Added libGLdispatch.so.0 to the AppImage to fix a crash introduced by a Mesa library update +* Updated the CImg library to commit 4d061dcd67c08e9a36a01875e78b53ee86501dd7 * Large refactoring to improve thread safety and improve singleton pattern usage * Made the logging thread safe * (Windows) Changed many logging entries to use backslashes instead of forward slashes as directory separators diff --git a/THEMES-DEV.md b/THEMES-DEV.md index 24d9fd813..cc4c0b9a8 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -525,16 +525,84 @@ Once the aspect ratios have been defined, they are applied to the theme configur ``` +## Transitions (animation profiles) + +Using the `capabilities.xml` file it's possible to define granular transition animation profiles. Prior to ES-DE 2.0 there was only a user-selectable option for _Instant_, _Slide_ or _Fade_ animations that were applied globally. It's now possible to define each of these animation types individually for the following transitions: + +* System to system +* System to gamelist +* Gamelist to gamelist +* Gamelist to system +* Startup to system +* Startup to gamelist + +Here's an example configuration: +```xml + + + true + instant + slide + instant + slide + fade + fade + + + + + true + instant + instant + instant + instant + +``` + +The `name` attribute is mandatory and it must be set to a unique value for each profile. Any string can be used except the three reserved values `builtin-instant`, `builtin-slide` and `builtin-fade`. + +The `selectable` property which is set to `true` by default defines whether the transition profile can be selected from the _Theme transition animations_ entry on the _UI Settings_ menu. The `label` defines the label to show there. If no label value is set then a default _Theme profile_ label will be applied. + +At least one of the six transition types must be defined or the `transitions` entry is not considered valid. Any non-defined types will be set to `instant` with the exception of `startupToSystem` which will be set to the same value as `systemToSystem` and `startupToGamelist` which will be set to the same value as `gamelistToGamelist`. + +The profiles will be listed in the _UI Settings_ menu in the order that they have been defined, and the first entry will be used if the _Automatic_ profile has been selected, unless a per-variant configuration is defined in the theme configuration. + +In addition to defining custom transition profiles it's possible to suppress the built-in profiles. For example slide transitions will look very broken with some theme designs so in such cases it could make sense to disable this animation type altogether. Suppressing a profile simply means its entry will not show up under _Theme transition animations_ in the _UI Settings_ menu, making it impossible to select and use it. + +Here's an example where all the built-in transition profiles have been disabled: + +```xml + + builtin-instant + builtin-slide + builtin-fade + +``` + +Regardless of whether any custom profiles have been created or whether the built-in profiles have been disabled there will always be an `Automatic` entry added to the _Theme transition animations_ menu. If no theme profiles have been defined and all built-in profiles have been suppressed, then the `Automatic` entry will be the only available option. In this case `instant` animations will by applied to all transition types. + +Finally it's possible to apply theme-defined transition profiles on a per-variant basis. This requires that the user has selected the `Automatic` profile from the _Theme transition animations_ menu as selecting any other profile will override whatever is defined in the theme configuration. Note that the built-in transition profiles can't be used in this manner, only profiles defined in `capabilities.xml`. + +```xml + + instantAndSlide + + + + instant + +``` + ## capabilities.xml -Variants, variant triggers, 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: +Variants, variant triggers, color schemes, aspect ratios and transition animation profiles 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 declarations for the variants, color schemes and aspect ratios, such as in this example: +The structure of the file is simple, as can be seen in this example: ```xml @@ -551,6 +619,13 @@ The structure of the file is simple, it just contains declarations for the varia + + instant + slide + instant + slide + + true @@ -577,11 +652,11 @@ The structure of the file is simple, it just contains declarations for the varia ``` -The file format is hopefully mostly self-explanatory; this example provides three aspect ratios, two color schemes and three variants, one of which is a variant trigger override. The `