From d0ccc8a13d42c7ab4e241a040497271bbc72425b Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Wed, 13 Oct 2021 18:47:34 +0200 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 1 + THEMES-DEV.md | 50 +++++++++++++++++++++--------------------------- USERGUIDE-DEV.md | 8 +++++--- 3 files changed, 28 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d7e306b4..a7a83df73 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -42,6 +42,7 @@ * Added support for key repeat to OptionListComponent, making it possible to cycle through the options by holding the left or right button * Added key repeat for the "Jump to" and "Sort games by" selectors on the game options menu * Added key repeat when editing the "Release date" entry in the metadata editor (DateTimeEditComponent) +* Added support for setting the Kidgame metadata flag for folders (which will only affect the badges) * Achieved a massive speed improvement for OptionListComponent by not resizing each added MenuComponent row (most notable in the filter GUI) * Made multiple optimizations to the GUI components by removing lots of unnecessary function calls for sizing, placement, opacity changes etc. * Simplified the logic for info popups and prepared the code for the future "multiple popups" feature diff --git a/THEMES-DEV.md b/THEMES-DEV.md index b2a659cf0..e13aea2c4 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -633,7 +633,7 @@ Can be created as an extra. * `rotation` - type: FLOAT. - angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. * `rotationOrigin` - type: NORMALIZED_PAIR. - - Point around which the image will be rotated. Defaults to `0.5 0.5`. + - Point around which the image will be rotated. Default is `0.5 0.5`. * `path` - type: PATH. - Path to the image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif). * `default` - type: PATH. @@ -707,7 +707,7 @@ Can be created as an extra. * `rotation` - type: FLOAT. - angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. * `rotationOrigin` - type: NORMALIZED_PAIR. - - Point around which the text will be rotated. Defaults to `0.5 0.5`. + - Point around which the text will be rotated. Default is `0.5 0.5`. * `delay` - type: FLOAT. Default is false. - Delay in seconds before video will start playing. * `default` - type: PATH. @@ -736,7 +736,7 @@ Can be created as an extra. * `rotation` - type: FLOAT. - angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. * `rotationOrigin` - type: NORMALIZED_PAIR. - - Point around which the text will be rotated. Defaults to `0.5 0.5`. + - Point around which the text will be rotated. Default is `0.5 0.5`. * `text` - type: STRING. * `color` - type: COLOR. * `backgroundColor` - type: COLOR; @@ -808,7 +808,7 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren * `rotation` - type: FLOAT. - angle in degrees that the rating should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. * `rotationOrigin` - type: NORMALIZED_PAIR. - - Point around which the rating will be rotated. Defaults to `0.5 0.5`. + - Point around which the rating will be rotated. Default is `0.5 0.5`. * `filledPath` - type: PATH. - Path to the "filled star" image. Image must be square (width equals height). * `unfilledPath` - type: PATH. @@ -832,7 +832,7 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren * `rotation` - type: FLOAT. - angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. * `rotationOrigin` - type: NORMALIZED_PAIR. - - Point around which the text will be rotated. Defaults to `0.5 0.5`. + - Point around which the text will be rotated. Default is `0.5 0.5`. * `color` - type: COLOR. * `backgroundColor` - type: COLOR; * `fontPath` - type: PATH. @@ -913,41 +913,35 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren * `pos` - type: NORMALIZED_PAIR. * `size` - type: NORMALIZED_PAIR. - Possible combinations: - - `w h` - Dimensions of the badges container. The badges will be scaled to fit within these dimensions. + - `w h` - Dimensions of the badges container. The badges will be scaled to fit within these dimensions. Minimum value per axis is `0.03`, maximum value is `1.0`. Default is `0.15 0.20`. * `origin` - type: NORMALIZED_PAIR. - - Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the component exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. + - Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the component exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. Default is `0 0`. * `rotation` - type: FLOAT. - - angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. + - angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. Default is `0`. * `rotationOrigin` - type: NORMALIZED_PAIR. - - Point around which the image will be rotated. Defaults to `0.5 0.5`. + - Point around which the image will be rotated. Default is `0.5 0.5`. * `itemsPerRow` - type: FLOAT. - - Number of badges that fit on a row. When more badges are available a new row will be started. + - Number of badges that fit on a row. When more badges are available a new row will be started. Default is `4`. * `rows` - type: FLOAT. - - The number of rows available. + - The number of rows available. Default is `2`. * `itemPlacement` - type: STRING. - - Valid values are "top", "center", "bottom", or "stretch". Controls vertical alignment of each badge if images of different heights are used. "Stretch" will stretch the badge to the full height. + - Valid values are "top", "center", "bottom", or "stretch". Controls vertical alignment of each badge if images of different heights are used. "Stretch" will stretch the badge to the full height. Default is `center`. * `itemMargin` - type: NORMALIZED_PAIR. - The margins between badges. Possible combinations: - - `x y` - horizontal and vertical margins. + - `x y` - horizontal and vertical margins. Minimum value per axis is `0`, maximum value is `0.2`. Default is `0.01`. * `slots` - type: STRING. - - The badge types that should be displayed. Should be specified as a list of strings separated by spaces. The order will be followed when placing badges on the screen. - - Available badges are: - - "favorite": Will be shown when the game is marked as favorite. - - "completed": Will be shown when the game is marked as completed. - - "kidgame": Will be shown when the game is marked as a kids game. - - "broken": Will be shown when the game is marked as broken. - - "altemulator": Will be shown when an alternative emulator is setup for the game. + - The badge types that should be displayed. Should be specified as a list of strings separated by spaces. The order will be followed when placing badges on the screen. Available badges are: + - `favorite`: Will be shown when the game is marked as favorite. + - `completed`: Will be shown when the game is marked as completed. + - `kidgame`: Will be shown when the game is marked as a kids game. + - `broken`: Will be shown when the game is marked as broken. + - `altemulator`: Will be shown when an alternative emulator is setup for the game. * `customBadgeIcon` - type: PATH. - - A badge icon override. Specify the badge type in the attribute `badge`. The available badges are: - `favorite`, - `completed`, - `kidgame`, - `broken`, - `altemulator` + - A badge icon override. Specify the badge type in the attribute `badge`. The available badges are the ones listed above. * `visible` - type: BOOLEAN. - If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. * `zIndex` - type: FLOAT. - - z-index value for component. Components will be rendered in order of z-index value from low to high. + - z-index value for component. Components will be rendered in order of z-index value from low to high. Default is `50`. #### carousel @@ -971,7 +965,7 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren - Default is 7.5 - This property only applies when `type` is "horizontal_wheel" or "vertical_wheel". * `logoRotationOrigin` - type: NORMALIZED_PAIR. - - Point around which the logos will be rotated. Defaults to `-5 0.5`. + - Point around which the logos will be rotated. Default is `-5 0.5`. - This property only applies when `type` is "horizontal_wheel" or "vertical_wheel". * `logoAlignment` - type: STRING. - Sets the alignment of the logos relative to the carousel. diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 34d760fd6..c0117dc04 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -213,6 +213,8 @@ In addition to the styles just described, there is a **Grid** view style as well If the theme supports it, there's a gamelist information field displayed in the gamelist view, showing the number of games for the system (total and favorites) as well as a folder icon if a folder has been entered. When applying any filters to the gamelist, the game counter is replaced with the amount of games filtered, as in 'filtered / total games', e.g. '19 / 77'. If there are game entries in the filter result that are marked not to be counted as games, the number of such files will be indicated as 'filtered + filtered non-games / total games', for example '23 + 4 / 77' indicating 23 normal games, 4 non-games out of a total of 77. Due to this approach it's theoretically possible that the combined filtered game amount exceeds the number of counted games in the collection, for instance '69 + 11 / 77'. This is not considered a bug and is so by design. This gamelist information field functionality is specific to EmulationStation Desktop Edition so older themes will not support this. +Another feature which requires theme support is **Badges**, which is a set of icons displaying the status for various metadata fields. The currently supported badge types are _favorite, completed, kidgame, broken_ and _alternative emulator_. If any of the first four metadata fields have been set for a game, their corresponding badges will be displayed, and if an alternative emulator has been selected for the specific game, that badge will be shown. Setting an alternative emulator system-wide will not display this badge as it's only intended to indicate game-specific overrides. + ![alt text](images/es-de_gamelist_view.png "ES-DE Gamelist View") _The **Gamelist view** is where you browse the games for a specific system._ @@ -1444,9 +1446,9 @@ A flag to indicate whether this is a favorite game. This flag can also be set di A flag to indicate whether you have completed the game. -**Kidgame** _(files only)_ +**Kidgame** -A flag to mark whether the game is suitable for children. This will be applied as a filter when starting ES-DE in _Kid_ mode. +A flag to mark whether the game is suitable for children. This will be applied as a filter when starting ES-DE in _Kid_ mode. Although it's possible to also set this flag for folders, this will **not** affect the actual files inside those folders. It will instead only be used to display the Kidgame badge for the folders themselves. **Hidden** @@ -1466,7 +1468,7 @@ Whether to exclude the file from the multi-scraper. This is quite useful in orde **Hide metadata fields** -This option will hide most metadata fields in the gamelist view. The intention is to be able to hide the fields for situations such as general folders (Multi-disc, Cartridges etc.) and for setup programs and similar (e.g. SETUP.EXE or INSTALL.BAT for DOS games). It could also be used on the game files for multi-disc games where perhaps only the .m3u playlist should have any metadata values. The only fields shown with this option enabled are the game name and description. Using the description it's possible to write some comments regarding the file or folder, should you want to. It's also possible to display game images and videos with this setting enabled. +This option will hide most metadata fields as well as any badges. The intention is to be able to hide the fields for situations such as general folders (Multi-disc, Cartridges etc.) and for setup programs and similar (e.g. SETUP.EXE or INSTALL.BAT for DOS games). It could also be used on the game files for multi-disc games where perhaps only the .m3u playlist should have any metadata values. The only fields shown with this option enabled are the game name and description. Using the description it's possible to write some comments regarding the file or folder, should you want to. It's also possible to display game images and videos with this setting enabled. **Times played** _(files only)_