From 54dd4ea6bbcbbc863f00a7de61e509d45846c866 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Fri, 13 Jan 2023 12:30:38 +0100 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 6 +- THEMES-DEV.md | 176 +++++++++++++++++++++++++---------------------- USERGUIDE-DEV.md | 14 ++-- 3 files changed, 107 insertions(+), 89 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ddbb738a1..9727c6b92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,8 @@ * Added support for 2x and 4x MSAA anti-aliasing (OpenGL renderer only) * (Windows) Made game launching more seamless by making the application window one pixel wider instead of one pixel less in height * gamelist.xml files are no longer loaded from the ROMs/system directories (although old behavior can be retained via an option in es_settings.xml) +* Added support for always grouping custom collections under the custom collections system regardless of theme set support +* Added support for mixed-case custom collection names * Expanded the quick system select menu option from an on/off entry to a selection of different button combinations * Changed the order of the help system entries Y, X, B and A to instead be listed as A, B, X and Y * Changed the start button for the screensaver from "Back" to "X" @@ -250,7 +252,8 @@ ### Bug fixes * Multiple levels of symlinking in the ROMs directory tree could crash the application on startup -* Adding a dot (.) to the es_systems.xml extension tag (to setup extensionless entries) lead to a crash if the system contained folders +* Adding a dot (.) to the es_systems.xml extension tag (to setup extensionless entries) led to a crash if the system contained folders +* Enabling collections from the Game Collection Settings menu could crash the application in some rare cases * Parsing of .desktop files on Unix did not properly handle escaping of % characters which made game launching fail for some RPCS3 games * For the cps system, MAME standalone was configured with the wrong system directory for the -rompath option, pointing to "arcade" instead of "cps" * During some menu operations that reloaded the gamelist view, the cached background could miss some components as they were not rendered in time @@ -277,6 +280,7 @@ * Using the trigger buttons to jump to the start or end of a gamelist did not reset any currently held navigation buttons * When a legacy theme set had a video view style but did not have a valid md_video entry then the video player would still start (and play the audio) * Clearing a game in the metadata editor would sometimes not remove all media files (if there were both a .jpg and a .png for a certain file type) +* Adding collections or changing collection settings could sometime lead to the gamelist not getting rendered until navigating away from the current system * The tile property for the image element did not work correctly with SVG images * Defining an itemScale (logoScale) property lower than 1.0 for the carousel did not work correctly * Carousel text did not get scaled/multiplied correctly with the itemScale property (bug retained for legacy themes for maximum backward compatibility) diff --git a/THEMES-DEV.md b/THEMES-DEV.md index 5ed390a6b..deefe7d73 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -116,10 +116,10 @@ Here is a very simple theme that changes the color of the game name text: ```xml - + 00FF00 - + 0.5 0.5 0.5 0.5 0.8 0.8 @@ -139,7 +139,7 @@ The `` tag pair refers to the available views within ES-DE, which is eithe Views are defined like this: ```xml - + ... define elements here ... ``` @@ -149,7 +149,7 @@ An element is a particular visual component such as an image, an animation or a This is the element structure: ```xml - + ... define properties here ... ``` @@ -158,7 +158,7 @@ Finally _properties_ control how a particular element looks and behaves, for exa [Reference](THEMES-DEV.md#reference) section. Properties are defined like this: ```xml -ValueHere +valueHere ``` Let's now put it all together. The following is a simple example of a text element which has its definition split across two separate XML files. @@ -166,7 +166,7 @@ Let's now put it all together. The following is a simple example of a text eleme ```xml - + 0.27 0.32 0.5 0.5 0.12 0.41 @@ -180,25 +180,25 @@ Let's now put it all together. The following is a simple example of a text eleme ```xml - + 707070 ``` -As long as the name attribute is identical, the element configuration will be combined automatically. But that is only true for elements of the same type, so for instance an image element could be defined that also uses _system_name_ for its name attribute without colliding with the text element: +As long as the name attribute is identical, the element configuration will be combined automatically. But that is only true for elements of the same type, so for instance an image element could be defined that also uses _systemName_ for its name attribute without colliding with the text element: ```xml - + 0.27 0.32 0.5 0.5 0.12 0.41 40 - + 0.49 0.8 0.4 0.28 35 @@ -207,14 +207,14 @@ As long as the name attribute is identical, the element configuration will be co ``` -Whether this is a good idea is another question, it would probably be better to set the name attribute for the image to _system_logo_ or similar for this example. +Whether this is a good idea is another question, it would probably be better to set the name attribute for the image to _systemLogo_ or similar for this example. In addition to this, if the name is used for the same element type but for different views, then there will also not be any collision: ```xml - + 0.04 0.73 0.5 0.5 0.12 0.22 @@ -222,7 +222,7 @@ In addition to this, if the name is used for the same element type but for diffe - + 0.27 0.32 0.5 0.5 0.12 0.41 @@ -247,7 +247,7 @@ Note that an unthemed system means precisely that, the specific system where the Sanitization for valid data format and structure is done in this manner, but verification that property values are actually correct (or reasonable) is handled by the individual component that takes care of creating and rendering the specific theme element. What happens in many instances is that a warning log entry is created and the invalid property is reset to its default value. So for these situations, the system will not become unthemed. Here's an example where a badges element accidentally had its horizontalAlignment property set to _leftr_ instead of _left_: ``` -Jan 28 17:25:27 Warn: BadgeComponent: Invalid theme configuration, property "horizontalAlignment" for element "gamelist_badges" defined as "leftr" +Jan 28 17:25:27 Warn: BadgeComponent: Invalid theme configuration, property "horizontalAlignment" for element "gamelistBadges" defined as "leftr" ``` Note however that warnings are not printed for all invalid properties as that would lead to an excessive amount of logging code. This is especially true for numeric values which are commonly just clamped to the allowable range without notifying the theme author. So make sure to check the [Reference](THEMES-DEV.md#reference) section of this document for valid values for each property. @@ -255,7 +255,7 @@ Note however that warnings are not printed for all invalid properties as that wo For more serious issues where it does not make sense to assign a default value or auto-adjust the configuration, an error log entry is generated and the element will in most instances not get rendered at all. Here's such an example where the imageType property for a video element was accidentally set to _covr_ instead of _cover_: ``` -Jan 28 17:29:11 Error: VideoComponent: Invalid theme configuration, property "imageType" for element "gamelist_video" defined as "covr" +Jan 28 17:29:11 Error: VideoComponent: Invalid theme configuration, property "imageType" for element "gamelistVideo" defined as "covr" ``` Error handling for missing files is handled a bit differently depending on whether the paths have been defined explicitly or via a variable. For explicitly defined paths a warning will be logged for element properties and an error will be triggered for include files. Here's an example of the latter case: @@ -308,7 +308,7 @@ Here are some example uses of the `` functionality: - + ./core/font.ttf 0.035 0.3 0.56 @@ -322,7 +322,7 @@ Here are some example uses of the `` functionality: -