From 61a8e527ed649718c2b1e13e28afb92d019267f3 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Mon, 26 Sep 2022 20:10:45 +0200 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 1 + FAQ.md | 6 +++++- THEMES-DEV.md | 17 +++++++++++++++-- USERGUIDE-DEV.md | 6 ++++-- USERGUIDE.md | 6 ++++-- 5 files changed, 29 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f77d9ad5..23b9bd8b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -140,6 +140,7 @@ * 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 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 * Changed all occurances of "GameList" to "Gamelist" throughout the codebase * Removed a huge amount of unnecessary Window* function parameters throughout the codebase diff --git a/FAQ.md b/FAQ.md index 88c864060..32d6f7c53 100644 --- a/FAQ.md +++ b/FAQ.md @@ -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? -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? diff --git a/THEMES-DEV.md b/THEMES-DEV.md index 30c4c40bf..f589ae256 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -811,10 +811,12 @@ Properties: - `fanart` - This will look for a fan art image. * `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. + - Default is `false` * `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. * `tile` - type: BOOLEAN - If true, the image will be tiled instead of stretched to fit its size. Useful for backgrounds. + - Default is `false` * `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. - 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. * `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. + - Default is `false` * `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. * `audio` - type: BOOLEAN @@ -969,6 +972,7 @@ Properties: - Default is `0.5 0.5` * `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. + - Default is `false` * `path` - type: PATH - Path to the animation file. Only the .json extension is supported. * `speed` - type: FLOAT. @@ -1181,10 +1185,12 @@ Properties: - `altemulator` - The alternative emulator for the game. Will be blank if none has been selected. * `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. + - Default is `false` * `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. * `container` - type: BOOLEAN - Whether the text should be placed inside a scrollable container. Only available for the `gamelist` view. + - Default is `false` * `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. - Default is `true` @@ -1299,6 +1305,7 @@ Properties: - %S: The second [00,59] * `displayRelative` - type: BOOLEAN. - Renders the datetime as a relative string (e.g. 'x days ago'). + - Default is `false` * `opacity` - type: FLOAT - Controls the level of transparency. If set to `0` the element will be disabled. - Minimum value is `0` and maximum value is `1` @@ -1423,8 +1430,6 @@ Properties: 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: * `system` * `gamelist` @@ -1524,6 +1529,7 @@ Properties: - Default is `0` * `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. + - Default is `false` * `reflectionsOpacity` - type: FLOAT - Defines the base opacity for the reflections. - 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). - Minimum value is `0.5` and maximum value is `3` - 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 - z-index value for element. Elements will be rendered in order of zIndex value from low to high. - Default is `50` @@ -1606,6 +1615,7 @@ Properties: - Path to image to render in place of "selector bar." * `selectorImageTile` - type: BOOLEAN - If true, the selector image will be tiled instead of stretched to fit its size. + - Default is `false` * `selectedColor` - type: COLOR - Color of the highlighted entry text. * `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 `!` - Valid values are `ascii` and `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 - z-index value for element. Elements will be rendered in order of zIndex value from low to high. - Default is `50` diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 844835246..f42613eda 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -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. -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): diff --git a/USERGUIDE.md b/USERGUIDE.md index 494915743..ffa28f7d1 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -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. -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):