mirror of
https://github.com/RetroDECK/ES-DE.git
synced 2024-11-21 21:55:38 +00:00
Documentation update
This commit is contained in:
parent
af69b1b0d2
commit
9fa5274792
|
@ -8,17 +8,22 @@
|
|||
|
||||
### Detailed list of changes
|
||||
|
||||
* Completely removed support for legacy EmulationStation themes
|
||||
* Removed the "Legacy gamelist view style" and "Legacy theme transitions" settings
|
||||
* Removed the "Display pillarboxes for gamelist videos" and "Render scanlines for gamelist videos" settings
|
||||
* Added support for pasting text into the application (when a text input field is focused)
|
||||
* Added support for using most characters (including multi-byte Unicode characters) in custom collection names
|
||||
* Added a new Utilities menu to the main menu
|
||||
* Added an entry to the Utilities menu for rescanning the ROM directory
|
||||
* Added a utility for removing orphaned data (game media, gamelist entries and custom collection entries)
|
||||
* Added ares standalone as an alternative emulator for the gamegear, gb, gba, gbc and satellaview systems
|
||||
* Changed the "no games" dialog to no longer save the ROM directory to es_settings.xml if its value hasn't changed
|
||||
* When editing custom collections with really long names, the "Y" helpsystem text now gets abbreviated
|
||||
* Removed Linux DEB package support from ApplicationUpdater as these packages are no longer provided
|
||||
* Changed ComponentList to fixed row heights which fixed many alignment issues
|
||||
* Improved the layout for the scraper and theme downloader to look more consistent across different display aspect ratios
|
||||
* Made the miximage offline generator GUI sizing more consistent across different display aspect ratios
|
||||
* Removed the es_log.txt entry when an es_systems.cfg legacy systems configuration file was found on startup
|
||||
* Improved menu system font rendering on GPUs without proper texture filtering support
|
||||
* Added theme support for the "manual" metadata type for the text element
|
||||
* Replaced a number of homecooked functions in FileSystemUtil with those from the C++ standard library
|
||||
|
@ -28,6 +33,8 @@
|
|||
|
||||
### Bug fixes
|
||||
|
||||
* Directories interpreted as files entries could not be removed from custom collections
|
||||
* (Windows) If the ROMDirectory setting had a value then all custom collection files contained absolute paths instead of relative paths
|
||||
* (Windows) Wide string conversions were not done correctly which caused issues when filenames contained 4-byte Unicode characters
|
||||
* (Windows) Attempting to capitalize multi-byte Unicode strings crashed the application if built using the MSVC compiler
|
||||
* The camera offset in ComponentList was not correctly calculated when reaching the bottom of a list
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
# EmulationStation Desktop Edition (ES-DE) v2.1 (development version) - Building and advanced configuration
|
||||
# EmulationStation Desktop Edition (ES-DE) v2.2 (development version) - Building and advanced configuration
|
||||
|
||||
This document is only relevant for the current ES-DE development version, if you would like to see the documentation for the latest stable release, refer to [INSTALL.md](INSTALL.md) instead.
|
||||
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
# EmulationStation Desktop Edition (ES-DE) v2.1 (development version) - Themes
|
||||
# EmulationStation Desktop Edition (ES-DE) v2.2 (development version) - Themes
|
||||
|
||||
**Note:** This document is only relevant for the current ES-DE development version, if you would like to see the documentation for the latest stable release, refer to [THEMES.md](THEMES.md) instead.
|
||||
|
||||
|
@ -86,9 +86,9 @@ If a theme set with the same name exists in both locations, the one in the home
|
|||
|
||||
## Differences to legacy RetroPie themes
|
||||
|
||||
If you are not familiar with theming for RetroPie or similar forks of EmulationStation you can skip this section as it only describes the key differences between the updated ES-DE themes and these _legacy_ theme sets. The term _legacy_ is used throughout this document to refer to this older style of themes which ES-DE still fully supports for backward compatibility reasons. The old theme format is described in [THEMES-LEGACY.md](THEMES-LEGACY.md) although this document is basically a historical artifact by now.
|
||||
If you are not familiar with theming for RetroPie or similar forks of EmulationStation then you can skip this section as it only describes the key differences between the updated ES-DE themes and these legacy theme sets. The term _legacy_ is used throughout this document to refer to this older style of themes. ES-DE as of 2.2.0 can no longer load legacy themes, so if you need to view them when porting them to ES-DE, either use a legacy EmulationStation fork or ES-DE 2.1.1.
|
||||
|
||||
With ES-DE v2.0 a new theme engine was introduced that fundamentally changed some aspects of how theming works. The previous design used specific view styles (basic, detailed, video and grid) and this was dropped completely and replaced with _variants_ that can accomplish the same thing while being much more powerful and flexible.
|
||||
With ES-DE 2.0.0 a new theme engine was introduced that fundamentally changed some aspects of how theming works. The previous design used specific view styles (basic, detailed, video and grid) and this was dropped completely and replaced with _variants_ that can accomplish the same thing while being much more powerful and flexible.
|
||||
|
||||
In the past EmulationStation basically had hardcoded view styles with certain elements always being present and only a limited ability to manipulate these via positioning, resizing, coloring etc. As well so-called _extras_ were provided to expand theming support somehow but even this was quite limited.
|
||||
|
||||
|
@ -681,12 +681,12 @@ Finally it's possible to apply theme-defined transition profiles on a per-varian
|
|||
|
||||
## capabilities.xml
|
||||
|
||||
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:
|
||||
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 be placed in the root of the theme directory, for example:
|
||||
```
|
||||
~/.emulationstation/themes/mythemeset-es-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 capabilities.xml file is mandatory and if it doesn't exist ES-DE will not attempt to load the theme.
|
||||
|
||||
The structure of the file is simple, as can be seen in this example:
|
||||
|
||||
|
@ -742,7 +742,7 @@ The structure of the file is simple, as can be seen in this example:
|
|||
```
|
||||
The file format is hopefully mostly self-explanatory; this example provides three aspect ratios, two color schemes, one transition animation profile and three variants, one of which is a variant trigger override. The `<label>` tag for the variants and transitions is the text that will show up in the _UI Settings_ menu, assuming `<selectable>` has been set to true. The same is true for color schemes, although these will always show up in the GUI and can't be disabled.
|
||||
|
||||
The optional `<themeName>` tag defines the name that will show up in the _Theme set_ option in the _UI Settings_ menu. If no such tag is present, then the physical directory name will be displayed instead, for example _MYTHEMESET-ES-DE_. Note that theme names will always be converted to uppercase characters when displayed in the menu. Legacy theme sets are also clearly marked with a _[LEGACY]_ suffix.
|
||||
The optional `<themeName>` tag defines the name that will show up in the _Theme set_ option in the _UI Settings_ menu. If no such tag is present, then the physical directory name will be displayed instead, for example _MYTHEMESET-ES-DE_. Note that theme names will always be converted to uppercase characters when displayed in the menu.
|
||||
|
||||
The variant, color scheme and transitions names as well as their labels can be set to arbitrary values, but the name has to be unique. If two entries are declared with the same name, a warning will be generated on startup and the duplicate entry will not get loaded. Variants, color schemes and transition animations will be listed in the _UI Settings_ menu in the order that they are defined in capabilities.xml.
|
||||
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
# EmulationStation Desktop Edition (ES-DE) v2.1 (development version) - User guide
|
||||
# EmulationStation Desktop Edition (ES-DE) v2.2 (development version) - User guide
|
||||
|
||||
This version of the user guide is only relevant for the current ES-DE development version, if you are using the latest stable release, refer to [USERGUIDE.md](USERGUIDE.md) instead.
|
||||
|
||||
|
@ -539,7 +539,7 @@ Quits the application. This key combination can be changed to Ctrl + Q, Alt + Q
|
|||
|
||||
ES-DE ships with the Slate and Modern theme sets and additional themes can be installed using the built-in theme downloader. More themes made specifically for ES-DE can be found on the Internet, and you can customize or create your own ones too.
|
||||
|
||||
You can also use most legacy RetroPie-compatible EmulationStation themes although support for these will be removed in a future release. Batocera and Recalbox themes are generally not compatible as these forks use a different theme engine than ES-DE.
|
||||
As of ES-DE 2.2.0 no legacy EmulationStation themes are supported, such as those from RetroPie ES. Only themes made specifically for ES-DE will work.
|
||||
|
||||
The new theme engine introduced in ES-DE 2.0.0 adds several user-selectable options to the _UI Settings_ menu, most notable _Theme variant_ which is essentially a form of theme profiles that the theme author can optionally implement. This could be anything, like different ways to navigate the themes, different layouts etc. Additionally _Theme color scheme_ support has been added and as the name implies it lets the theme author implement multiple color schemes into their design. The other two new options _Theme aspect ratio_ and _Theme transitions_ are also important but you can normally leave them at their default _Automatic_ values, especially the _Theme aspect ratio_ option as it will be automatically detected.
|
||||
|
||||
|
@ -2373,11 +2373,11 @@ Starts the theme downloader, which is documented in detail [elsewhere](USERGUIDE
|
|||
|
||||
**Theme set**
|
||||
|
||||
The theme set to use. Defaults to Slate which is shipped with the application. There are two types of theme sets; the new type which was introduced with ES-DE v2.0 and legacy themes that are supported for backward compatibility with RetroPie EmulationStation. The use of legacy themes is however discouraged as their functionality is very limited. As well the backward compabitility will likely be removed at some point in the future.
|
||||
The theme set to use. Defaults to Slate which is shipped with the application.
|
||||
|
||||
**Theme variant**
|
||||
|
||||
Non-legacy theme sets optionally support variants which are a type of theme profiles defined by the theme author. This could be things like different designs or whether videos are enabled or not.
|
||||
Theme sets optionally support variants which are a type of theme profiles defined by the theme author. This could be things like different designs or whether videos are enabled or not.
|
||||
|
||||
**Theme color scheme**
|
||||
|
||||
|
@ -2385,20 +2385,12 @@ If the theme author has included multiple color schemes, then these can be selec
|
|||
|
||||
**Theme aspect ratio**
|
||||
|
||||
Non-legacy theme sets could optionally be optimized for different screen aspect ratios. ES-DE supports 16:9, 16:10, 3:2, 4:3, 5:4, 21:9 and 32:9 in both horizontal and vertical orientation, but it's completely up to the theme author which of these are actually supported by the theme set. It's normally best to leave this setting at _Automatic_ in which case ES-DE will automatically select the aspect ratio that most closely matches the screen resolution. The _Automatic_ option is however only available if the theme set supports at least two aspect ratios.
|
||||
Theme sets could optionally be optimized for different screen aspect ratios. ES-DE supports 16:9, 16:10, 3:2, 4:3, 5:4, 21:9 and 32:9 in both horizontal and vertical orientation, but it's completely up to the theme author which of these are actually supported by the theme set. It's normally best to leave this setting at _Automatic_ in which case ES-DE will automatically select the aspect ratio that most closely matches the screen resolution. The _Automatic_ option is however only available if the theme set supports at least two aspect ratios.
|
||||
|
||||
**Theme transitions**
|
||||
|
||||
Transition animations to play when navigating between gamelists, between systems in the System view and between the system and gamelist views. It's normally recommended to keep this setting at its default _Automatic_ value as that allows per-variant transitions, assuming the theme author has included support for that in their theme set. For example there could be multiple theme-defined transition entries to choose from, or there could be the possibility to make a selection between the built-in _Instant_, _Slide_ and _Fade_ transitions (although these options could have been disabled from the theme configuration). If there are no user-selectable transitions avaialable the setting will be grayed out.
|
||||
|
||||
**Legacy gamelist view style**
|
||||
|
||||
Sets the view style to _Automatic, Basic, Detailed or Video_ for legacy themes. See the description [above](USERGUIDE-DEV.md#gamelist-view) in this document for more information regarding view styles. _Variants_ have replaced gamelist view styles for non-legacy themes so this option will be grayed out if a modern theme set has been selected.
|
||||
|
||||
**Legacy theme transitions**
|
||||
|
||||
Transition animations to play when navigating between gamelists, between systems on the system view carousel and between the system and gamelist views. Can be set to _Instant_, _Slide_ or _Fade_. Only applicable for legacy themes as current theme sets let the theme author define transition animations in a more fine-grained manner. Therefore this option will be grayed out if a non-legacy theme set has been selected.
|
||||
|
||||
**Quick system select**
|
||||
|
||||
The buttons to use to jump between systems in the gamelist view. The options are _Left/right or shoulders_, _Left/right or triggers_, _Shoulders_, _Triggers_, _Left/right_ or _Disabled_. The first two options will apply either left/right or shoulder/trigger buttons depending on the type of primary element used for the gamelist. For example a textlist or a vertical carousel will allow the use of the left and right buttons, but for horizontal carousels and grids these buttons are reserved for navigating the entries so instead the secondary buttons will be used, i.e. the shoulder or trigger buttons. Using these two options therefore leads to a slight inconsistency as different buttons will be used depending on the theme configuration. If instead using any of the single button pair options, i.e. _Shoulders_, _Triggers_ or _Left/right_, the navigation will be consistent regardless of theme configuration but you'll sacrifice the ability to use the selected buttons if the gamelist supports it, such as the ability to jump rows in a textlist using the shoulder and trigger buttons.
|
||||
|
@ -2441,20 +2433,12 @@ Submenu containing all the settings for the screensaver. These are described in
|
|||
|
||||
**Enable theme variant triggers**
|
||||
|
||||
Non-legacy theme sets can optionally contain variant trigger configuration which changes the layout on a per-gamelist basis if there is no game media available, or if there is no game videos available. This option makes it possible to disable that functionality and always apply the default configuration for the selected variant.
|
||||
Theme sets can optionally contain variant trigger configuration which changes the layout on a per-gamelist basis if there is no game media available, or if there is no game videos available. This option makes it possible to disable that functionality and always apply the default configuration for the selected variant.
|
||||
|
||||
**Blur background when menu is open** _Always applied if screen is rotated 90 or 270 degrees_
|
||||
|
||||
This option will blur the background behind the menu slightly. Normally this can be left enabled, but if you have a really slow GPU, disabling this option may make the application feel a bit more responsive. For technical reasons this setting is always enabled if the screen is rotated 90 or 270 degrees, and in this case the menu option will also be grayed out.
|
||||
|
||||
**Display pillarboxes for gamelist videos** _Only for legacy theme sets_
|
||||
|
||||
With this option enabled, there are black pillarboxes (and to a lesser extent letterboxes) displayed around videos with non-standard aspect ratios. This will probably be most commonly used for vertical arcade shooters, or for game systems that has a screen in portrait orientation. For wider than normal videos, letterboxes are added, but this is quite rare compared to videos in portrait orientation. This option looks good with some theme sets such as Slate, but on others it may be more visually pleasing to disable it. On less wide displays such as those in 4:3 aspect ratio this option should probably be disabled as it may otherwise add quite excessive letterboxing. This option is only available for legacy theme sets as it's otherwise managed by the theme author.
|
||||
|
||||
**Render scanlines for gamelist videos** _Only for legacy theme sets_
|
||||
|
||||
Whether to use a shader to render scanlines for videos in the gamelist view. The effect is usually pretty subtle as the video is normally renderered in a limited size in the GUI and the scanlines are sized relative to the video window size. This option is only available for legacy theme sets as it's otherwise managed by the theme author.
|
||||
|
||||
**Sort folders on top of gamelists**
|
||||
|
||||
Whether to place all folders on top of the gamelists. If enabled the folders will not be part of the quick selector index, meaning they can no longer be quick-jumped to. That is, unless there are only folders in the gamelist in which case the folders will be handled like files.
|
||||
|
|
Loading…
Reference in a new issue