Documentation update.

CONTRIBUTING.md

@@ -76,7 +76,7 @@ This plan is under constant review so expect it to change from time to time. Sti
 * Migration tools for importing game metadata and media from other front-end applications
 * Auto-import tools for Steam, Lutris etc.
 
-To see which features have been implemented in previous versions, refer to [NEWS.md](NEWS.md).
+To see which features have been implemented in previous versions, refer to [RELEASES.md](RELEASES.md).
 
 ### Coding style:
 

INSTALL.md

@@ -934,8 +934,8 @@ You can use `--help` or `-h` to view a list of command line options, as shown he
 --max-vram [size]               Max VRAM to use (in mebibytes) before swapping
 --gpu-statistics                Display framerate and VRAM usage overlay
 --force-full                    Force the UI mode to Full
---force-kid                     Force the UI mode to Kid
 --force-kiosk                   Force the UI mode to Kiosk
+--force-kid                     Force the UI mode to Kid
 --force-input-config            Force configuration of input device
 --home [path]                   Directory to use as home path
 --version, -v                   Displays version information
@@ -956,8 +956,8 @@ You can use `--help` or `-h` to view a list of command line options, as shown he
 --max-vram [size]               Max VRAM to use (in mebibytes) before swapping
 --gpu-statistics                Display framerate and VRAM usage overlay
 --force-full                    Force the UI mode to Full
---force-kid                     Force the UI mode to Kid
 --force-kiosk                   Force the UI mode to Kiosk
+--force-kid                     Force the UI mode to Kid
 --force-input-config            Force configuration of input device
 --home [path]                   Directory to use as home path
 --version, -v                   Displays version information
@@ -978,8 +978,8 @@ You can use `--help` or `-h` to view a list of command line options, as shown he
 --max-vram [size]               Max VRAM to use (in mebibytes) before swapping
 --gpu-statistics                Display framerate and VRAM usage overlay
 --force-full                    Force the UI mode to Full
---force-kid                     Force the UI mode to Kid
 --force-kiosk                   Force the UI mode to Kiosk
+--force-kid                     Force the UI mode to Kid
 --force-input-config            Force configuration of input device
 --home [path]                   Directory to use as home path
 --version, -v                   Displays version information

README.md

@@ -42,7 +42,7 @@ If you would like to contribute to the development of ES-DE, then that's great!
 
 # Other information
 
-[NEWS.md](NEWS.md) contains information about the current release as well as previous releases. This covers the features, improvements and bug fixes.
+[RELEASES.md](RELEASES.md) contains information about the current release as well as previous releases. This covers the features, improvements and bug fixes.
 
 [INSTALL.md](INSTALL.md) provides details on how to build the application from source code, and also discusses some more advanced configuration topics.
 
@@ -54,32 +54,32 @@ If you would like to contribute to the development of ES-DE, then that's great!
 
 Here are some highlights of what EmulationStation Desktop Edition provides, displayed using the default theme set rbsimple-DE. There are of course many more features available, please refer to the [User Guide](USERGUIDE.md) for a comprehensive overview of all options and functionality.
 
-![alt text](images/v1.0/es-de_v1.0_system_view.png "ES-DE System View")
+![alt text](images/current/es-de_system_view.png "ES-DE System View")
 _The 'System view', which is the default starting point for the application, it's here that you browse through your game systems._
 
-![alt text](images/v1.0/es-de_v1.0_gamelist_view.png "ES-DE Gamelist View")
+![alt text](images/current/es-de_gamelist_view.png "ES-DE Gamelist View")
 _The 'Gamelist view', it's here that you browse the games for a specific system. Note the support for mixing files and folders, and as well that favorite games are marked with stars. There is a game counter to the upper right, displaying the total number of games and the number of favorite games for this system._
 
-![alt text](images/v1.0/es-de_v1.0_folder_support.png "ES-DE Folder Support")
+![alt text](images/current/es-de_folder_support.png "ES-DE Folder Support")
 _Another example of the gamelist view, displaying advanced folder support. You can scrape folders for game info and game media, sort folders as you would files, mark them as favorites etc. In this example ES-DE has been configured to sort favorite games above non-favorites._
 
-![alt text](images/v1.0/es-de_v1.0_custom_collections.png "ES-DE Custom Collections")
+![alt text](images/current/es-de_custom_collections.png "ES-DE Custom Collections")
 _Games can be grouped into your own custom collections, in this example they're defined as game genres but you can name them anything you like. All gamelist views including the custom collections support both game images or game videos. By default the rbsimple-DE theme will display the game image for a short moment before starting to play the game video._
 
-![alt text](images/v1.0/es-de_v1.0_scraper_running.png "ES-DE Scraper Running")
+![alt text](images/current/es-de_scraper_running.png "ES-DE Scraper Running")
 _This is a view of the built-in scraper which downloads game info and game media from either [screenscraper.fr](https://screenscraper.fr) or [thegamesdb.net](https://thegamesdb.net). It's possible to scrape a single game, or to run the multi-scraper which can scrape a complete game system or even your entire collection._
 
-![alt text](images/v1.0/es-de_v1.0_scraper_settings.png "ES-DE Scraper Settings")
+![alt text](images/current/es-de_scraper_settings.png "ES-DE Scraper Settings")
 _There are many settings for the scraper including options to define which type of info and media to download. The above screenshot shows only a portion of all these settings._
 
-![alt text](images/v1.0/es-de_v1.0_metadata_editor.png "ES-DE Metadata Editor")
+![alt text](images/current/es-de_metadata_editor.png "ES-DE Metadata Editor")
 _In addition to the scraper there is a fully-featured metadata editor that can be used to modify information on a per-game basis. Here you can also toggle some additional flags which the scraper does not set, such as if the game is a favorite, or if you have completed it. Some of these flags can then be filtered in the gamelist view, letting you for instance only list games that you have not played through._
 
-![alt text](images/v1.0/es-de_v1.0_screensaver.png "ES-DE Screensaver")
+![alt text](images/current/es-de_screensaver.png "ES-DE Screensaver")
 _There are four types of built-in screensavers available, including a slideshow and the video screensaver showed in action above. These screensavers start after a configurable number of minutes of inactivity, and randomly display game media that you have previously scraped. If the corresponding option has been enabled, you can jump to the game from the screensaver, or even start it directly. There is shader support in ES-DE to render scanlines and screen blur on top of the videos (for the slideshow, scanline rendering is provided)._
 
-![alt text](images/v1.0/es-de_v1.0_ui_theme_support.png "ES-DE Theme Support")
+![alt text](images/current/es-de_ui_theme_support.png "ES-DE Theme Support")
 _ES-DE is fully themeable, so if you prefer another look than what the default theme rbsimple-DE gives you, it's possible to apply another theme set. In the example above a modified version of the [Fundamental](https://github.com/G-rila/es-theme-fundamental) theme is used. Be aware though that although ES-DE is backwards compatible with older EmulationStation themes, some newer features which are specific to ES-DE will not work, at least not until the theme authors update their themes._
 
-![alt text](images/v1.0/es-de_v1.0_ui_easy_setup.png "ES-DE Easy Setup")
+![alt text](images/current/es-de_ui_easy_setup.png "ES-DE Easy Setup")
 _A lot of effort has been spent on trying to make ES-DE easy to setup and use. The above screenshot shows the dialog if starting the application without any game files present in the default ROM directory. Also, ES-DE ships with a very comprehensive game systems configuration file that is automatically installed upon first startup. Note though that the emulator setup is outside the scope of what ES-DE does, and as RetroArch is mostly used, please refer to their [web site](https://www.retroarch.com) for more information about that part of the configuration._

RELEASES.md

@@ -1,16 +1,18 @@
-# EmulationStation Desktop Edition v1.0.0
+# EmulationStation Desktop Edition (ES-DE) Releases
 
-**Release date:** YYYY-MM-DD
+## Version 1.0.0 (in development)
+
+**Release date:** TBD
 
 ### Release overview
 
-First release, a major update to the application compared to the RetroPie version on which it is based. This includes new gamelist sorting logic, new game media handling and an updated Windows port as well as a macOS port (which both work about as well as the Unix version). The menu system has also been completely overhauled and the scraper has been expanded to support multiple media types (including videos) as well as providing detailed scraping configuration options.
+First release, a major update to the application compared to the RetroPie version on which it is based. This includes new gamelist sorting logic, new game media handling and an updated Windows port as well as a macOS port. The menu system has also been completely overhauled and the scraper has been expanded to support multiple media types as well as providing detailed scraping configuration options.
 
 Full navigation sound support has been implemented, and the metadata editor has seen a lot of updates including color coding of all changes done by the user and by the scraper. Favorite games can now also be sorted on top of the gamelists and game collections.
 
 OpenGL GLSL shader support has been added (not for the OpenGL ES renderer though) and there are multiple effects implemented such as scanlines for videos, blurred background when opening menus etc.
 
-A new default theme rbsimple-DE (based on Recalbox Multi) is bundled with the application and is part of the installation package/installer. However themes created for other EmulationStation ports should still work correctly.
+A new default theme rbsimple-DE (based on Recalbox Multi) is bundled with the application and is part of the installation package/installer. However themes created for other EmulationStation forks should still work correctly.
 
 Many bugs have been fixed, and numerous features that were only partially implemented or broken have been updated to a fully working state. The application runs much faster as well due to lots of optimizations.
 
@@ -90,6 +92,7 @@ Many bugs have been fixed, and numerous features that were only partially implem
 * Unknown command line options were silently accepted instead of generating an error and notifying the user
 * The scraper didn't handle error conditions correctly
 * Fixed a massive memory leak related to SVG images
+* Fixed an issue where SVG images would sometimes be cut off slightly on the right side (e.g. logos on the system view carousel)
 * Toggling the screensaver didn't work as expected
 * Wrapping around the first and last game systems generated strange camera movements when using the slide transition style
 * Game media was not rendered when moving between gamelists using the slide transition style

USERGUIDE.md

@@ -32,7 +32,7 @@ The installation procedure is just covered briefly here and may differ a bit for
 
 **Installing a Linux .deb package**
 
-Thes .deb package is used for Linux distributions based on Debian, such as Ubuntu, Linux Mint etc.
+The .deb package is used for Linux distributions based on Debian, such as Ubuntu, Linux Mint etc.
 Running the following should install ES-DE and resolve any dependencies:
 
 ```
@@ -47,7 +47,7 @@ On Fedora you run this command to install ES-DE, which should automatically reso
 sudo dnf install ./emulationstation-de-1.0.0.rpm
 ```
 
-Note that this requires the RPM Fusion repository as there's a depedency on VLC, which is not part of the standard operating system repo. See [INSTALL.md](INSTALL.md#building-on-unix) for details on how to add this.
+Note that this requires the RPM Fusion repository as there's a dependency on VLC, which is not part of the standard operating system repo. See [INSTALL.md](INSTALL.md#building-on-unix) for details on how to add this.
 
 **Installing on macOS and Windows**
 
@@ -82,7 +82,7 @@ As an alternative to this, you can also modify es_systems.cfg which will be loca
 
 After ES-DE finds at least one game file, it will populate that game system and the application will start. If there are no game files, an error messsage will be shown, explaining that you need to install your game files into your ROM directory. You will also be given a choice to change the ROM directory if you don't want to use the default path. Please refer to the game installation procedure below in this document for more information regarding this.
 
-![alt text](images/v1.0/es-de_v1.0_ui_easy_setup.png "ES-DE Easy Setup")
+![alt text](images/current/es-de_ui_easy_setup.png "ES-DE Easy Setup")
 _This is the error dialog shown if no game files were found. It also lets you configure the ROM directory if you don't want to use the default one. Note that the directory is the real physical path, and that your operating system may present this as a localized path if you are using a language other than English._
 
 
@@ -122,7 +122,7 @@ Depending on the theme, the system navigation carousel can be either horizontal
 
 The game systems are sorted by their full names, as defined in es_systems.cfg.
 
-![alt text](images/v1.0/es-de_v1.0_system_view.png "ES-DE System View")
+![alt text](images/current/es-de_system_view.png "ES-DE System View")
 _The System view is the default starting point for the application, it's here that you browse through your game systems._
 
 ## Gamelist view
@@ -139,9 +139,24 @@ In additions to the styles just described, there is a **Grid** view style as wel
 
 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 like '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.
 
-![alt text](images/v1.0/es-de_v1.0_gamelist_view.png "ES-DE Gamelist View")
+![alt text](images/current/es-de_gamelist_view.png "ES-DE Gamelist View")
 _The Gamelist view is where you browse the games for a specific system._
 
+
+## UI modes
+
+ES-DE supports three separate modes, **Full**, **Kiosk** and **Kid**.
+
+These modes mandate the functionalty provided by the application in the following way:
+
+* Full - This is the default mode which enables all functionality.
+* Kiosk - The main menu will be severely restricted, only displaying the entry to change the system audio volume. The game options menu will be restricted as well, removing the metadata editor and the ability to modify custom game collections. And finally the ability to flag games as favorites will be removed. Apart from this all games will be playable.
+* Kid - Only games marked as being suitable for children will be displayed (this flag is set manually per game using the metadata editor). Additionally, the game options menu is disabled, as well as the screensaver controls and the ability to flag games as favorites. There is also a separate option available to enable or disable the main menu when in Kid mode, see **Enable menu in kid mode** further [below](USERGUIDE.md#other-settings-1)
+
+There is an unlock code available to revert to the full mode from the Kiosk or Kid mode, as is described when changing this setting from the main menu. By default the button sequence is **Up, Up, Down, Down, Left, Right, Left, Right, B, A**. It works to use either a keyboard or a configured controller to input the passkey sequence, but it can't be entered when a menu is open.
+
+The application can also be forced into any of the three modes via the command line options **-force-full**, **--force-kiosk** and **-force-kid**. Note that this is only temporary until the restart of the application, unless the settings menu is entered and the setting is saved to the configuration file. (This assumes that the main menu is available in the selected UI mode of course).
+
 ## Help system
 
 There is a help system available throughout the application that provides an overview of the possible actions and buttons that can be used. It's possible to disable the help system for a somewhat cleaner look using a menu option. Note that some general button actions are never shown, such as the ability to quick jump in gamelists, menus and text input fields using the shoulder and trigger buttons.
@@ -482,7 +497,7 @@ The category **Other game metadata** includes Description, Release date, Develop
 
 There are two approaches to scraping, either for a single game from the metadata editor, or for many games and systems using the multi-scraper.
 
-![alt text](images/v1.0/es-de_v1.0_scraper_running.png "ES-DE Scraper Running")
+![alt text](images/current/es-de_scraper_running.png "ES-DE Scraper Running")
 _Here's an example of the multi-scraper running in interactive-mode, asking the user to make a selection from the multiple matching games returned by the scraper service._
 
 ### Single-game scraper
@@ -547,7 +562,7 @@ As an alternative, you can also locate your game media in the ROM directory. Thi
 
 Note that it's possible to change the game media directory from within ES-DE, see the option **Game media directory** detailed below.
 
-![alt text](images/v1.0/es-de_v1.0_scraper_settings.png "ES-DE Scraper Settings")
+![alt text](images/current/es-de_scraper_settings.png "ES-DE Scraper Settings")
 _Some of the scraper settings._
 
 ## Main menu
@@ -692,7 +707,7 @@ The theme to use. Defaults to rbsimple-DE, the theme shipped with EmulationStati
 
 **UI mode**
 
-Defaults to Full which enables all functionality within the application. If set to Kid, only games marked as being suitable for children will be displayed (this flag is set manually per game using the metadata editor). Additionally, the game options menu is disabled, as well as the screensaver controls and the ability to flag games as favorites. There is also a separate option available to enable or disable the main menu when in Kid mode, see 'Enable menu in kid mode' further below. In Kiosk mode, the main menu will be available, but it will only display the entry to change the system audio volume. The game options menu will be usable, but the metadata editor and the ability to modify custom game collections will be disabled. Finally, screensaver controls will be enabled when in Kiosk mode.
+Sets the mode for the application, as described in detail [above](USERGUIDE.md#ui-modes).
 
 **Default sort order**
 
@@ -823,9 +838,17 @@ Whether to use a shader to render a slight horizontal blur which somewhat simula
 
 General sound settings.
 
-**System volume**
+**System volume** _(Unix and Windows only)_
 
-As the name implies, this sets the overall system volume and not the volume specifically for ES-DE.
+As the name implies, this sets the overall system volume and not the volume specifically for ES-DE. Note that the volume change is applied only after leaving the sound settings menu.
+
+**Navigation sounds volume**
+
+Sets the volume for the navigation sounds.
+
+**Video player volume**
+
+Sets the volume for the video player. This applies to both the gamelist views and the video screensaver.
 
 **Play audio for video files in gamelist views**
 
@@ -902,7 +925,7 @@ Here you can override the directory to your game media, i.e. the game images and
 
 **Emulator core path**
 
-This setting defines the path for which to search for emulator cores. This is used by the variable %COREPATH% which can be defined in the systems configuration file es_systems.cfg. By default this variable and corresponding setting is only used on Unix. For macOS and Windows it's not included in the es_systems.cfg template and the default core path value is therefore set to blank. If required for special setups it can be used for these operating systems, but the primary use is on Unix where the core path may vary depending on the operating system, how the emulator was packaged etc. For example the default RetroArch core directory is ~/.config/retroarch/cores but if installed as a Snap package or as part of the OS repository the cores could be stored elsewhere. The setting is primarily intended for RetroArch but it can be used for any emulator that utilizes discrete emulator cores. When attempting to launch a game, the core for the game system will be searched in each of the defined directories until the first match occurs. Multiple directories can be defined by separating them using colons on Unix and macOS and semicolons on Windows. Please see [INSTALL.md](INSTALL.md#es_systemscfg) for more information about this.
+This setting defines the path for which to search for emulator cores. This is used by the variable %COREPATH% which can be defined in the systems configuration file es_systems.cfg. By default this variable and corresponding setting is only used on Unix. For macOS and Windows it's not included in the es_systems.cfg template and the default core path value is therefore set to blank. If required for special setups it can be used for these operating systems, but the primary use is on Unix where the core path may vary depending on the operating system, how the emulator was packaged etc. For example the default RetroArch core directory is ~/.config/retroarch/cores but if installed as a Snap package or as part of the OS repository the cores could be stored elsewhere. The setting is primarily intended for RetroArch but it can be used for any emulator that utilizes discrete emulator cores. When attempting to launch a game, the core for the game system will be searched in each of the defined directories until the first match occurs. Multiple directories can be defined by separating them using colons on Unix and macOS and by semicolons on Windows. Please see [INSTALL.md](INSTALL.md#es_systemscfg) for more information about this.
 
 **Per game launch command override**
 
@@ -1028,7 +1051,7 @@ This menu entry is only visible when editing the collection.
 
 In the metadata editor, you can modify the metadata for a game, scrape for game info and media files and delete media files and gamelist entries, or the entire game.
 
-![alt text](images/v1.0/es-de_v1.0_metadata_editor.png "ES-DE Metadata Editor")
+![alt text](images/current/es-de_metadata_editor.png "ES-DE Metadata Editor")
 _The metadata editor._
 
 ### Metadata entries
@@ -1146,7 +1169,7 @@ The _Dim_ screensaver simply dims and desaturates the current view and _Black_ w
 
 If the option **Enable screensaver controls** has been activated, you can manually toggle the screensaver from the system view by pressing the 'Select' key. In addition to this, the controls will allow you to jump to a new random image or video using the left and right buttons on your keyboard or controller. It's also possible to launch the game currently displayed by pressing the 'A' button, and pressing the 'Y' button will jump to the game in its gamelist without starting it.
 
-![alt text](images/v1.0/es-de_v1.0_screensaver.png "ES-DE Screensaver")
+![alt text](images/current/es-de_screensaver.png "ES-DE Screensaver")
 _An example of what the video screensaver looks like._
 
 ## Game collections
@@ -1189,7 +1212,7 @@ When you are done adding games, you can either open the main menu and go to 'Gam
 
 You can later add additional games to the collection by navigating to it, bringing up the game options menu and choosing 'Add/remove games to this game collection'.
 
-![alt text](images/v1.0/es-de_v1.0_custom_collections.png "ES-DE Custom Collections")
+![alt text](images/current/es-de_custom_collections.png "ES-DE Custom Collections")
 _Example of custom collections, here configured as genres._
 
 The way that custom collection are implemented is very simple. There is a folder for the collections in `~/.emulationstation/collections` with a separate file for each collection.
@@ -1245,7 +1268,7 @@ https://gitlab.com/recalbox/recalbox-themes
 
 https://wiki.batocera.org/themes
 
-![alt text](images/v1.0/es-de_v1.0_ui_theme_support.png "ES-DE Theme Support")
+![alt text](images/current/es-de_ui_theme_support.png "ES-DE Theme Support")
 _An example of a modified version of the [Fundamental](https://github.com/G-rila/es-theme-fundamental) theme applied._