Xargon/ES-DE
1
0
Fork 0
mirror of https://github.com/RetroDECK/ES-DE.git synced 2024-11-25 07:35:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2022-09-26 20:10:45 +02:00
parent 06fd76abc3
commit 61a8e527ed
5 changed files with 29 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
CHANGELOG.md
View file

@ -140,6 +140,7 @@
* Added a new itemAxisHorizontal property to the carousel to keep wheel items horizontal at all times * Added a new itemAxisHorizontal property to the carousel to keep wheel items horizontal at all times
* Added carousel theme support for setting the opacity for unfocused entries * Added carousel theme support for setting the opacity for unfocused entries
* Added carousel theme support for setting item transitions to "slide" or "instant" * Added carousel theme support for setting item transitions to "slide" or "instant"
* Added a fadeAbovePrimary property to control whether elements above the system view carousel and textlist should be rendered during fade transitions
* Removed support for the thumbnail game media type * Removed support for the thumbnail game media type
* Changed all occurances of "GameList" to "Gamelist" throughout the codebase * Changed all occurances of "GameList" to "Gamelist" throughout the codebase
* Removed a huge amount of unnecessary Window* function parameters throughout the codebase * Removed a huge amount of unnecessary Window* function parameters throughout the codebase

6
FAQ.md
View file

@ -18,7 +18,11 @@ ES-DE runs on Windows, macOS and BSD Unix as well as on multiple Linux distribut
## What is the relationship between ES-DE and EmuDeck? ## What is the relationship between ES-DE and EmuDeck?
ES-DE and EmuDeck are completely separate projects, but we collaborate to give the best possible user experience. EmuDeck is an installation script that downloads emulators and applies configuration to these, and it can also download and install ES-DE. EmuDeck is not needed to run ES-DE, but on the Steam Deck it provides a convenient way of setting up an emulator environment for people not experienced with making this type of installation and configuration on their own. It's a good idea to read the _Specific notes for Steam Deck_ section of the [User guide](USERGUIDE.md#specific-notes-for-steam-deck) if ES-DE has been installed using EmuDeck. ES-DE and [EmuDeck](http://www.emudeck.com) are completely separate projects, but we collaborate to give the best possible user experience. EmuDeck is an installer that downloads emulators and applies configuration to these, and it can also download and install ES-DE. EmuDeck is not needed to run ES-DE, but on the Steam Deck it provides a convenient way of setting up an emulator environment for people not experienced with making this type of installation and configuration on their own. It's a good idea to read the _Specific notes for Steam Deck_ section of the [User guide](USERGUIDE.md#specific-notes-for-steam-deck) if ES-DE has been installed using EmuDeck.
## What is the relationship between ES-DE and RetroDECK?
ES-DE and [RetroDECK](http://retrodeck.net) are completely separate projects, but we collaborate to give the best possible user experience. RetroDECK bundles ES-DE with all emulators in the same Flatpak so you don't need to update emulators separately or set Flatpak permissions manually. It's a good idea to read the _Specific notes for Steam Deck_ section of the [User guide](USERGUIDE.md#specific-notes-for-steam-deck) if ES-DE has been installed via RetroDECK.
## What systems/platforms and emulators are supported by ES-DE? ## What systems/platforms and emulators are supported by ES-DE?

17
THEMES-DEV.md
View file

@ -811,10 +811,12 @@ Properties:
- `fanart` - This will look for a fan art image. - `fanart` - This will look for a fan art image.
* `metadataElement` - type: BOOLEAN * `metadataElement` - type: BOOLEAN
- By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the _Hide metadata fields_ setting for a game entry. Using this property it's possible to explicitly define additional image elements that should be treated as if they were game media files. This is for example useful for hiding and fading out image elements that are used as indicator icons for the various metadata types like genre, publisher, players etc. It's however not possible to do the opposite, i.e. to disable this functionality for the default game media types as that would break basic application behavior. - By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the _Hide metadata fields_ setting for a game entry. Using this property it's possible to explicitly define additional image elements that should be treated as if they were game media files. This is for example useful for hiding and fading out image elements that are used as indicator icons for the various metadata types like genre, publisher, players etc. It's however not possible to do the opposite, i.e. to disable this functionality for the default game media types as that would break basic application behavior.
- Default is `false`
* `gameselector` - type: STRING * `gameselector` - type: STRING
- If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `imageType` property is utilized. - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `imageType` property is utilized.
* `tile` - type: BOOLEAN * `tile` - type: BOOLEAN
- If true, the image will be tiled instead of stretched to fit its size. Useful for backgrounds. - If true, the image will be tiled instead of stretched to fit its size. Useful for backgrounds.
- Default is `false`
* `tileSize` - type: NORMALIZED_PAIR * `tileSize` - type: NORMALIZED_PAIR
- Size of the individual images making up the tile as opposed to the overall size for the element which is defined by the `size` property. If only one axis is specified (and the other is zero), then the other axis will be automatically calculated in accordance with the image's aspect ratio. Setting both axes to 0 is an error and tiling will be disabled in this case. If scaling SVG images to non-standard aspect ratios, be aware that rasterization is always done while maintaining aspect ratio and the stretching or squashing is done using the GPU. This means that the image quality will not be that good if excessive stretching is done to such images. If this property is omitted, then the size will be set to the actual image dimensions. For SVG images this means whatever canvas size has been defined inside the file. - Size of the individual images making up the tile as opposed to the overall size for the element which is defined by the `size` property. If only one axis is specified (and the other is zero), then the other axis will be automatically calculated in accordance with the image's aspect ratio. Setting both axes to 0 is an error and tiling will be disabled in this case. If scaling SVG images to non-standard aspect ratios, be aware that rasterization is always done while maintaining aspect ratio and the stretching or squashing is done using the GPU. This means that the image quality will not be that good if excessive stretching is done to such images. If this property is omitted, then the size will be set to the actual image dimensions. For SVG images this means whatever canvas size has been defined inside the file.
- Minimum value per axis is `0` and maximum value per axis is `1`. - Minimum value per axis is `0` and maximum value per axis is `1`.
@ -900,6 +902,7 @@ Properties:
- `fanart` - This will look for a fan art image. - `fanart` - This will look for a fan art image.
* `metadataElement` - type: BOOLEAN * `metadataElement` - type: BOOLEAN
- By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the _Hide metadata fields_ setting for a game entry. Using this property it's possible to explicitly define static video elements that should be treated as if they were game media files. This property is ignored if `path` is not set. - By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the _Hide metadata fields_ setting for a game entry. Using this property it's possible to explicitly define static video elements that should be treated as if they were game media files. This property is ignored if `path` is not set.
- Default is `false`
* `gameselector` - type: STRING * `gameselector` - type: STRING
- If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element.
* `audio` - type: BOOLEAN * `audio` - type: BOOLEAN
@ -969,6 +972,7 @@ Properties:
- Default is `0.5 0.5` - Default is `0.5 0.5`
* `metadataElement` - type: BOOLEAN * `metadataElement` - type: BOOLEAN
- By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the _Hide metadata fields_ setting for a game entry. Using this property it's possible to explicitly define animation elements that should be treated as if they were game media files. This is for example useful for hiding and fading out animations that are used as indicators for the various metadata types like genre, publisher, players etc. - By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the _Hide metadata fields_ setting for a game entry. Using this property it's possible to explicitly define animation elements that should be treated as if they were game media files. This is for example useful for hiding and fading out animations that are used as indicators for the various metadata types like genre, publisher, players etc.
- Default is `false`
* `path` - type: PATH * `path` - type: PATH
- Path to the animation file. Only the .json extension is supported. - Path to the animation file. Only the .json extension is supported.
* `speed` - type: FLOAT. * `speed` - type: FLOAT.
@ -1181,10 +1185,12 @@ Properties:
- `altemulator` - The alternative emulator for the game. Will be blank if none has been selected. - `altemulator` - The alternative emulator for the game. Will be blank if none has been selected.
* `metadataElement` - type: BOOLEAN * `metadataElement` - type: BOOLEAN
- By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the _Hide metadata fields_ setting for a game entry. Using this property it's possible to explicitly define additional text elements that should be treated as if they were game metadata entries. This is for example useful for hiding and fading out text labels for the various metadata types like genre, publisher, players etc. Note that it's not possible to disable the metadata hiding functionality for the default metadata fields as that would break basic application behavior. Also note that there is a slight exception to the hiding logic for text containers with the metadata value set to `description`. In this case the element is by default not hidden when enabling the _Hide metadata fields_ setting. To also hide such containers, set this property to true. - By default game metadata and media are faded out during gamelist fast-scrolling and text metadata fields, ratings and badges are hidden when enabling the _Hide metadata fields_ setting for a game entry. Using this property it's possible to explicitly define additional text elements that should be treated as if they were game metadata entries. This is for example useful for hiding and fading out text labels for the various metadata types like genre, publisher, players etc. Note that it's not possible to disable the metadata hiding functionality for the default metadata fields as that would break basic application behavior. Also note that there is a slight exception to the hiding logic for text containers with the metadata value set to `description`. In this case the element is by default not hidden when enabling the _Hide metadata fields_ setting. To also hide such containers, set this property to true.
- Default is `false`
* `gameselector` - type: STRING * `gameselector` - type: STRING
- If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `metadata` property is utilized. - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `metadata` property is utilized.
* `container` - type: BOOLEAN * `container` - type: BOOLEAN
- Whether the text should be placed inside a scrollable container. Only available for the `gamelist` view. - Whether the text should be placed inside a scrollable container. Only available for the `gamelist` view.
- Default is `false`
* `containerVerticalSnap` - type: BOOLEAN * `containerVerticalSnap` - type: BOOLEAN
- Whether the text should be vertically snapped to the font height. With this property enabled the container will have its height reduced as needed so that only complete rows of text are displayed at the start and end positions. This will not affect the "real" size of the container as set by the `size` property which means that the overall element placement will still be predictable if a vertical origin other than zero is used. - Whether the text should be vertically snapped to the font height. With this property enabled the container will have its height reduced as needed so that only complete rows of text are displayed at the start and end positions. This will not affect the "real" size of the container as set by the `size` property which means that the overall element placement will still be predictable if a vertical origin other than zero is used.
- Default is `true` - Default is `true`
@ -1299,6 +1305,7 @@ Properties:
- %S: The second [00,59] - %S: The second [00,59]
* `displayRelative` - type: BOOLEAN. * `displayRelative` - type: BOOLEAN.
- Renders the datetime as a relative string (e.g. 'x days ago'). - Renders the datetime as a relative string (e.g. 'x days ago').
- Default is `false`
* `opacity` - type: FLOAT * `opacity` - type: FLOAT
- Controls the level of transparency. If set to `0` the element will be disabled. - Controls the level of transparency. If set to `0` the element will be disabled.
- Minimum value is `0` and maximum value is `1` - Minimum value is `0` and maximum value is `1`
@ -1423,8 +1430,6 @@ Properties:
A carousel for navigating and selecting games or systems. A carousel for navigating and selecting games or systems.
On the system view when using fade transitions, any elements placed below or at the same zIndex value as the carousel will be faded to black during transitions, and any elements with a higher zIndex value than the carousel will be faded to transparent. These two fading methods do not mix well, so if you for example want to overlay some elements with a semi-transparent mask or similar, make sure to keep this in mind. As long as the elements are all above or below the carousel everything will look fine.
Supported views: Supported views:
* `system` * `system`
* `gamelist` * `gamelist`
@ -1524,6 +1529,7 @@ Properties:
- Default is `0` - Default is `0`
* `reflections` - type: BOOLEAN * `reflections` - type: BOOLEAN
- Enables reflections beneath the carousel items. This is only available for the `horizontal` carousel type. It's probably a good idea to combine this with the `verticalOffset` property to define how much of the reflections should be visible. - Enables reflections beneath the carousel items. This is only available for the `horizontal` carousel type. It's probably a good idea to combine this with the `verticalOffset` property to define how much of the reflections should be visible.
- Default is `false`
* `reflectionsOpacity` - type: FLOAT * `reflectionsOpacity` - type: FLOAT
- Defines the base opacity for the reflections. - Defines the base opacity for the reflections.
- Minimum value is `0.1` and maximum value is `1` - Minimum value is `0.1` and maximum value is `1`
@ -1564,6 +1570,9 @@ Properties:
- Controls the space between lines (as a multiple of font height). - Controls the space between lines (as a multiple of font height).
- Minimum value is `0.5` and maximum value is `3` - Minimum value is `0.5` and maximum value is `3`
- Default is `1.5` - Default is `1.5`
* `fadeAbovePrimary` - type: BOOLEAN
- When using fade transitions, all elements in the `system` view with a zIndex value higher than the carousel are by default still rendered during transitions. If this property is enabled then all such elements will instead be faded out. Note that elements below the carousel will be dimmed to black and elements above the carousel will be faded to transparent.
- Default is `false`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `50` - Default is `50`
@ -1606,6 +1615,7 @@ Properties:
- Path to image to render in place of "selector bar." - Path to image to render in place of "selector bar."
* `selectorImageTile` - type: BOOLEAN * `selectorImageTile` - type: BOOLEAN
- If true, the selector image will be tiled instead of stretched to fit its size. - If true, the selector image will be tiled instead of stretched to fit its size.
- Default is `false`
* `selectedColor` - type: COLOR * `selectedColor` - type: COLOR
- Color of the highlighted entry text. - Color of the highlighted entry text.
* `primaryColor` - type: COLOR * `primaryColor` - type: COLOR
@ -1636,6 +1646,9 @@ Properties:
- Controls the style of the indicators which get displayed when editing a custom collection. This property can't be disabled as it's crucial for getting a visual overview when editing collections. When set to `ascii`, the indicator is displayed as a `!` - Controls the style of the indicators which get displayed when editing a custom collection. This property can't be disabled as it's crucial for getting a visual overview when editing collections. When set to `ascii`, the indicator is displayed as a `!`
- Valid values are `ascii` and `symbols` - Valid values are `ascii` and `symbols`
- Default is `symbols` - Default is `symbols`
* `fadeAbovePrimary` - type: BOOLEAN
- When using fade transitions, all elements in the `system` view with a zIndex value higher than the textlist are by default still rendered during transitions. If this property is enabled then all such elements will instead be faded out. Note that elements below the textlist will be dimmed to black and elements above the textlist will be faded to transparent.
- Default is `false`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `50` - Default is `50`

6
USERGUIDE-DEV.md
View file

@ -313,9 +313,11 @@ Another problem on macOS 11 Big Sur (and possibly older OS versions) is that whe
As the Steam Deck is essentially a Linux desktop computer with a custom user interface, there is really not much to consider when running ES-DE on this device, except that SteamOS uses an immutable filesystem which adds some restrictions not present in most other Linux distributions. There is a specific AppImage available for the Steam Deck though that is recommended to use, as some settings have been tuned for the best possible experience on this device. As the Steam Deck is essentially a Linux desktop computer with a custom user interface, there is really not much to consider when running ES-DE on this device, except that SteamOS uses an immutable filesystem which adds some restrictions not present in most other Linux distributions. There is a specific AppImage available for the Steam Deck though that is recommended to use, as some settings have been tuned for the best possible experience on this device.
It is possible to install ES-DE using [EmuDeck](https://www.emudeck.com) which will automatically download the latest Steam Deck-specific release. Just be aware that if using EmuDeck you will have a non-standard ES-DE installation as this installation script makes some customizations to paths and other settings. This guide only covers default installations so in case you see something mentioned that doesn't match your setup, then make sure to contact the EmuDeck support. Also be aware that re-running the EmuDeck script could potentially be a destructive operation as some files and settings may be overwritten. It's also possible to install ES-DE using [EmuDeck](https://www.emudeck.com) which will automatically download the latest Steam Deck-specific release. Just be aware that if using EmuDeck you will have a non-standard ES-DE installation as their installer makes some customizations to paths and other settings. This guide only covers default installations so in case you see something mentioned that doesn't match your setup, make sure to contact the EmuDeck support.
For Flatpak releases of some emulators you may need to give extra permissions to be able to launch games placed on external devices such as a memory card. This is the case for instance for melonDS and RPCS3. The easiest way to do this is by using [Flatseal](https://flathub.org/apps/details/com.github.tchx84.Flatseal). The option you need to enable is _All system files_ in the _Filesystem_ section. For Flatpak releases of some emulators you may need to give extra permissions to be able to launch games placed on external devices such as a memory card. This is the case for instance for melonDS and RPCS3. The easiest way to do this is by using [Flatseal](https://flathub.org/apps/details/com.github.tchx84.Flatseal). The option you need to enable is generally _All system files_ in the _Filesystem_ section. If using EmuDeck some of these settings will be applied automatically via their installer.
As an alternative to EmuDeck you could use [RetroDECK](http://retrodeck.net) which is shipped as a Flatpak and can be easily installed via Discover. As RetroDECK bundles all its emulators inside the Flatpak you don't need to update any emulators separately or set Flatpak permissions manually. The drawback compared to using EmuDeck or running ES-DE standalone is that less systems and emulators are supported. Most popular systems should work fine though and more emulators are getting added continuously so the situation will improve over time. Also note that if going for this approach you will have a non-standard ES-DE installation and some parts of this user guide will not apply.
If you are unfamiliar with Unix operating systems, make sure to at least read up on the concepts of _dotfiles_ (hidden files and directories), _home directories_ (including use of the tilde ~ character) and _symbolic links_ (symlinks): If you are unfamiliar with Unix operating systems, make sure to at least read up on the concepts of _dotfiles_ (hidden files and directories), _home directories_ (including use of the tilde ~ character) and _symbolic links_ (symlinks):

6
USERGUIDE.md
View file

@ -311,9 +311,11 @@ Another problem on macOS 11 Big Sur (and possibly older OS versions) is that whe
As the Steam Deck is essentially a Linux desktop computer with a custom user interface, there is really not much to consider when running ES-DE on this device, except that SteamOS uses an immutable filesystem which adds some restrictions not present in most other Linux distributions. There is a specific AppImage available for the Steam Deck though that is recommended to use, as some settings have been tuned for the best possible experience on this device. As the Steam Deck is essentially a Linux desktop computer with a custom user interface, there is really not much to consider when running ES-DE on this device, except that SteamOS uses an immutable filesystem which adds some restrictions not present in most other Linux distributions. There is a specific AppImage available for the Steam Deck though that is recommended to use, as some settings have been tuned for the best possible experience on this device.
It is possible to install ES-DE using [EmuDeck](https://www.emudeck.com) which will automatically download the latest Steam Deck-specific release. Just be aware that if using EmuDeck you will have a non-standard ES-DE installation as this installation script makes some customizations to paths and other settings. This guide only covers default installations so in case you see something mentioned that doesn't match your setup, then make sure to contact the EmuDeck support. Also be aware that re-running the EmuDeck script could potentially be a destructive operation as some files and settings may be overwritten. It's also possible to install ES-DE using [EmuDeck](https://www.emudeck.com) which will automatically download the latest Steam Deck-specific release. Just be aware that if using EmuDeck you will have a non-standard ES-DE installation as their installer makes some customizations to paths and other settings. This guide only covers default installations so in case you see something mentioned that doesn't match your setup, make sure to contact the EmuDeck support.
For Flatpak releases of some emulators you may need to give extra permissions to be able to launch games placed on external devices such as a memory card. This is the case for instance for melonDS and RPCS3. The easiest way to do this is by using [Flatseal](https://flathub.org/apps/details/com.github.tchx84.Flatseal). The option you need to enable is _All system files_ in the _Filesystem_ section. For Flatpak releases of some emulators you may need to give extra permissions to be able to launch games placed on external devices such as a memory card. This is the case for instance for melonDS and RPCS3. The easiest way to do this is by using [Flatseal](https://flathub.org/apps/details/com.github.tchx84.Flatseal). The option you need to enable is generally _All system files_ in the _Filesystem_ section. If using EmuDeck some of these settings will be applied automatically via their installer.
As an alternative to EmuDeck you could use [RetroDECK](http://retrodeck.net) which is shipped as a Flatpak and can be easily installed via Discover. As RetroDECK bundles all its emulators inside the Flatpak you don't need to update any emulators separately or set Flatpak permissions manually. The drawback compared to using EmuDeck or running ES-DE standalone is that less systems and emulators are supported. Most popular systems should work fine though and more emulators are getting added continuously so the situation will improve over time. Also note that if going for this approach you will have a non-standard ES-DE installation and some parts of this user guide will not apply.
If you are unfamiliar with Unix operating systems, make sure to at least read up on the concepts of _dotfiles_ (hidden files and directories), _home directories_ (including use of the tilde ~ character) and _symbolic links_ (symlinks): If you are unfamiliar with Unix operating systems, make sure to at least read up on the concepts of _dotfiles_ (hidden files and directories), _home directories_ (including use of the tilde ~ character) and _symbolic links_ (symlinks):