From 4c075a7b6fd5396fb7762b0781dda267c6d3117b Mon Sep 17 00:00:00 2001 From: Fabrice CARUSO Date: Mon, 21 Oct 2019 17:35:36 +0200 Subject: [PATCH] Update Themes & general documentations --- GAMELISTS.md | 1 - README.md | 387 +++++++++++++++++++---------------------- THEMES.md | 482 +++++++++++++++++++++++++++++++++++++++++++-------- 3 files changed, 591 insertions(+), 279 deletions(-) diff --git a/GAMELISTS.md b/GAMELISTS.md index 7064a27ca..6d83c1c44 100644 --- a/GAMELISTS.md +++ b/GAMELISTS.md @@ -54,7 +54,6 @@ Some metadata is also marked as "statistic" - these are kept track of by ES and * `players` - integer, the number of players the game supports. * `playcount` - statistic, integer, the number of times this game has been played. * `lastplayed` - statistic, datetime, the last date and time this game was played. -* `sortname` - string, used in sorting the gamelist in a system, instead of `name`. #### `` diff --git a/README.md b/README.md index 06bfee35c..c816703a1 100644 --- a/README.md +++ b/README.md @@ -1,103 +1,111 @@ -EmulationStation -================ - -This is a fork of EmulationStation for RetroPie. -EmulationStation is a cross-platform graphical front-end for emulators with controller navigation. - -Building -======== - -EmulationStation uses some C++11 code, which means you'll need to use at least g++-4.7 on Linux, or VS2010 on Windows, to compile. - -EmulationStation has a few dependencies. For building, you'll need CMake, SDL2, FreeImage, FreeType, cURL and RapidJSON. You also should probably install the `fonts-droid` package which contains fallback fonts for Chinese/Japanese/Korean characters, but ES will still work fine without it (this package is only used at run-time). - -**On Debian/Ubuntu:** -All of this be easily installed with `apt-get`: -```bash -sudo apt-get install libsdl2-dev libsdl2-mixer-dev libfreeimage-dev libfreetype6-dev \ - libcurl4-openssl-dev rapidjson-dev libasound2-dev libgl1-mesa-dev build-essential \ - libboost-all-dev cmake fonts-droid-fallback libvlc-dev libvlccore-dev vlc-bin -``` -**On Fedora:** -All of this be easily installed with `dnf` (with rpmfusion activated) : -```bash -sudo dnf install SDL2-devel freeimage-devel freetype-devel curl-devel \ - alsa-lib-devel mesa-libGL-devel cmake \ - vlc-devel rapidjson-devel -``` - -Note this Repository uses a git submodule - to checkout the source and all submodules, use - -```bash -git clone --recursive https://github.com/RetroPie/EmulationStation.git -``` - -or - -```bash -git clone https://github.com/RetroPie/EmulationStation.git -cd EmulationStation -git submodule update --init -``` - -Then, generate and build the Makefile with CMake: -```bash -cd YourEmulationStationDirectory -cmake . -make -``` - -**On the Raspberry Pi:** - -Complete Raspberry Pi build instructions at [emulationstation.org](http://emulationstation.org/gettingstarted.html#install_rpi_standalone). - -**On Windows:** - -[FreeImage](http://downloads.sourceforge.net/freeimage/FreeImage3154Win32.zip) - -[FreeType2](http://download.savannah.gnu.org/releases/freetype/freetype-2.4.9.tar.bz2) (you'll need to compile) - -[SDL2](http://www.libsdl.org/release/SDL2-devel-2.0.8-VC.zip) - -[cURL](http://curl.haxx.se/download.html) (you'll need to compile or get the pre-compiled DLL version) - -[RapisJSON](https://github.com/tencent/rapidjson) (you'll need the `include/rapidsjon` added to the include path) - -(Remember to copy necessary .DLLs into the same folder as the executable: probably FreeImage.dll, freetype6.dll, SDL2.dll, libcurl.dll, and zlib1.dll. Exact list depends on if you built your libraries in "static" mode or not.) - -[CMake](http://www.cmake.org/cmake/resources/software.html) (this is used for generating the Visual Studio project) - -(If you don't know how to use CMake, here are some hints: run cmake-gui and point it at your EmulationStation folder. Point the "build" directory somewhere - I use EmulationStation/build. Click configure, choose "Visual Studio [year] Project", fill in red fields as they appear and keep clicking Configure (you may need to check "Advanced"), then click Generate.) - - -Configuring -=========== - -**~/.emulationstation/es_systems.cfg:** -When first run, an example systems configuration file will be created at `~/.emulationstation/es_systems.cfg`. `~` is `$HOME` on Linux, and `%HOMEPATH%` on Windows. This example has some comments explaining how to write the configuration file. See the "Writing an es_systems.cfg" section for more information. - -**Keep in mind you'll have to set up your emulator separately from EmulationStation!** - -**~/.emulationstation/es_input.cfg:** -When you first start EmulationStation, you will be prompted to configure an input device. The process is thus: - -1. Hold a button on the device you want to configure. This includes the keyboard. - -2. Press the buttons as they appear in the list. Some inputs can be skipped by holding any button down for a few seconds (e.g. page up/page down). - -3. You can review your mappings by pressing up and down, making any changes by pressing A. - -4. Choose "SAVE" to save this device and close the input configuration screen. - -The new configuration will be added to the `~/.emulationstation/es_input.cfg` file. - -**Both new and old devices can be (re)configured at any time by pressing the Start button and choosing "CONFIGURE INPUT".** From here, you may unplug the device you used to open the menu and plug in a new one, if necessary. New devices will be appended to the existing input configuration file, so your old devices will remain configured. - -**If your controller stops working, you can delete the `~/.emulationstation/es_input.cfg` file to make the input configuration screen re-appear on next run.** - - -You can use `--help` or `-h` to view a list of command-line options. Briefly outlined here: -``` +EmulationStation +================ + +EmulationStation is a cross-platform graphical front-end for emulators with controller navigation. + +Building +======== + +EmulationStation uses some C++11 code, which means you'll need to use at least g++-4.7 on Linux, or Visual Studio 2015 on Windows, to compile. + +EmulationStation has a few dependencies. For building, you'll need CMake, SDL2, FreeImage, FreeType, cURL, RapidJSON, LibVLC, SDLMixer. You also should probably install the `fonts-droid` package which contains fallback fonts for Chinese/Japanese/Korean characters, but ES will still work fine without it (this package is only used at run-time). + +**On Debian/Ubuntu:** +All of this be easily installed with `apt-get`: +```bash +sudo apt-get install libsdl2-dev libsdl2-mixer-dev libfreeimage-dev libfreetype6-dev \ + libcurl4-openssl-dev rapidjson-dev libasound2-dev libgl1-mesa-dev build-essential \ + libboost-all-dev cmake fonts-droid-fallback libvlc-dev libvlccore-dev vlc-bin +``` +**On Fedora:** +All of this be easily installed with `dnf` (with rpmfusion activated) : +```bash +sudo dnf install SDL2-devel freeimage-devel freetype-devel curl-devel \ + alsa-lib-devel mesa-libGL-devel cmake \ + vlc-devel rapidjson-devel +``` + +Note this Repository uses a git submodule - to checkout the source and all submodules, use + +```bash +git clone --recursive https://github.com/RetroPie/EmulationStation.git +``` + +or + +```bash +git clone https://github.com/RetroPie/EmulationStation.git +cd EmulationStation +git submodule update --init +``` + +Then, generate and build the Makefile with CMake: +```bash +cd YourEmulationStationDirectory +cmake . +make +``` + +**On the Raspberry Pi:** + +Complete Raspberry Pi build instructions at [emulationstation.org](http://emulationstation.org/gettingstarted.html#install_rpi_standalone). + +**On Windows:** + +[FreeImage](http://downloads.sourceforge.net/freeimage/FreeImage3154Win32.zip) + +[FreeType2](http://download.savannah.gnu.org/releases/freetype/freetype-2.4.9.tar.bz2) (you'll need to compile) + +[SDL2](http://www.libsdl.org/release/SDL2-devel-2.0.8-VC.zip) + +[cURL](http://curl.haxx.se/download.html) (you'll need to compile or get the pre-compiled DLL version) + +[RapisJSON](https://github.com/tencent/rapidjson) (you'll need the `include/rapidsjon` added to the include path) + +[SDL Mixer](https://www.libsdl.org/projects/SDL_mixer/) + +[LibVlc](http://download.videolan.org/pub/videolan/vlc/) (x86 sdk files are present in .7z files) + +[CMake](http://www.cmake.org/cmake/resources/software.html) (this is used for generating the Visual Studio project) + +``` +set ES_LIB_DIR=c:\src\lib + +mkdir c:\src\batocera-emulationstation\build +cd c:\src\batocera-emulationstation\build /D + +cmake -g "Visual Studio 14 2015 x86" .. -DEIGEN3_INCLUDE_DIR=%ES_LIB_DIR%\eigen -DRAPIDJSON_INCLUDE_DIRS=%ES_LIB_DIR%\rapidjson\include -DFREETYPE_INCLUDE_DIRS=%ES_LIB_DIR%\freetype-2.7\include -DFREETYPE_LIBRARY=%ES_LIB_DIR%\freetype-2.7\objs\vc2010\Win32\freetype27.lib -DFreeImage_INCLUDE_DIR=%ES_LIB_DIR%\FreeImage\Source -DFreeImage_LIBRARY=%ES_LIB_DIR%\FreeImage\Dist\x32\FreeImage.lib -DSDL2_INCLUDE_DIR=%ES_LIB_DIR%\SDL2-2.0.9\include -DSDL2_LIBRARY=%ES_LIB_DIR%\SDL2-2.0.9\build\Release\SDL2.lib;%ES_LIB_DIR%\SDL2-2.0.9\build\Release\SDL2main.lib;Imm32.lib;version.lib -DBOOST_ROOT=%ES_LIB_DIR%\boost_1_61_0 -DBoost_LIBRARY_DIR=%ES_LIB_DIR%\boost_1_61_0\lib32-msvc-14.0 -DCURL_INCLUDE_DIR=%ES_LIB_DIR%\curl-7.50.3\include -DCURL_LIBRARY=%ES_LIB_DIR%\curl-7.50.3\builds\libcurl-vc14-x86-release-dll-ipv6-sspi-winssl\lib\libcurl.lib -DVLC_INCLUDE_DIR=%ES_LIB_DIR%\libvlc-2.2.2\include -DVLC_LIBRARIES=%ES_LIB_DIR%\libvlc-2.2.2\lib\msvc\libvlc.lib;%ES_LIB_DIR%\libvlc-2.2.2\lib\msvc\libvlccore.lib -DVLC_VERSION=1.0.0 -DSDLMIXER_INCLUDE_DIR=%ES_LIB_DIR%\SDL2_mixer-2.0.4\include -DSDLMIXER_LIBRARY=%ES_LIB_DIR%\SDL2_mixer-2.0.4\lib\x86\SDL2_mixer.lib +``` + + +Configuring +=========== + +**~/.emulationstation/es_systems.cfg:** +When first run, an example systems configuration file will be created at `~/.emulationstation/es_systems.cfg`. `~` is `$HOME` on Linux, and `%HOMEPATH%` on Windows. This example has some comments explaining how to write the configuration file. See the "Writing an es_systems.cfg" section for more information. + +**Keep in mind you'll have to set up your emulator separately from EmulationStation!** + +**~/.emulationstation/es_input.cfg:** +When you first start EmulationStation, you will be prompted to configure an input device. The process is thus: + +1. Hold a button on the device you want to configure. This includes the keyboard. + +2. Press the buttons as they appear in the list. Some inputs can be skipped by holding any button down for a few seconds (e.g. page up/page down). + +3. You can review your mappings by pressing up and down, making any changes by pressing A. + +4. Choose "SAVE" to save this device and close the input configuration screen. + +The new configuration will be added to the `~/.emulationstation/es_input.cfg` file. + +**Both new and old devices can be (re)configured at any time by pressing the Start button and choosing "CONFIGURE INPUT".** From here, you may unplug the device you used to open the menu and plug in a new one, if necessary. New devices will be appended to the existing input configuration file, so your old devices will remain configured. + +**If your controller stops working, you can delete the `~/.emulationstation/es_input.cfg` file to make the input configuration screen re-appear on next run.** + + +You can use `--help` or `-h` to view a list of command-line options. Briefly outlined here: +``` --resolution [width] [height] try and force a particular resolution --gamelist-only skip automatic game search, only read from gamelist.xml --ignore-gamelist ignore the gamelist (useful for troubleshooting) @@ -107,112 +115,79 @@ You can use `--help` or `-h` to view a list of command-line options. Briefly out --debug more logging, show console on Windows --scrape scrape using command line interface --windowed not fullscreen, should be used with --resolution +--fullscreen-borderless fullscreen, non exclusive. --vsync [1/on or 0/off] turn vsync on or off (default is on) --max-vram [size] Max VRAM to use in Mb before swapping. 0 for unlimited ---force-kid Force the UI mode to be Kid ---force-kiosk Force the UI mode to be Kiosk +--force-kid Force the UI mode to be Kid +--force-kiosk Force the UI mode to be Kiosk --force-disable-filters Force the UI to ignore applied filters in gamelist ---help, -h summon a sentient, angry tuba -``` - -As long as ES hasn't frozen, you can always press F4 to close the application. - - -Writing an es_systems.cfg -========================= - -Complete configuration instructions at [emulationstation.org](http://emulationstation.org/gettingstarted.html#config). - -The `es_systems.cfg` file contains the system configuration data for EmulationStation, written in XML. This tells EmulationStation what systems you have, what platform they correspond to (for scraping), and where the games are located. - -ES will check two places for an es_systems.cfg file, in the following order, stopping after it finds one that works: -* `~/.emulationstation/es_systems.cfg` -* `/etc/emulationstation/es_systems.cfg` - -The order EmulationStation displays systems reflects the order you define them in. - -**NOTE:** A system *must* have at least one game present in its "path" directory, or ES will ignore it! If no valid systems are found, ES will report an error and quit! - -Here's an example es_systems.cfg: - -```xml - - - - - - - snes - - - Super Nintendo Entertainment System - - - ~/roms/snes - - - .smc .sfc .SMC .SFC - - - snesemulator %ROM% - - - - snes - - - snes - - -``` - -The following "tags" are replaced by ES in launch commands: - -`%ROM%` - Replaced with absolute path to the selected ROM, with most Bash special characters escaped with a backslash. - -`%BASENAME%` - Replaced with the "base" name of the path to the selected ROM. For example, a path of "/foo/bar.rom", this tag would be "bar". This tag is useful for setting up AdvanceMAME. - -`%ROM_RAW%` - Replaced with the unescaped, absolute path to the selected ROM. If your emulator is picky about paths, you might want to use this instead of %ROM%, but enclosed in quotes. - -See [SYSTEMS.md](SYSTEMS.md) for some live examples in EmulationStation. - -gamelist.xml -============ - -The gamelist.xml file for a system defines metadata for games, such as a name, image (like a screenshot or box art), description, release date, and rating. - -If at least one game in a system has an image specified, ES will use the detailed view for that system (which displays metadata alongside the game list). - -*You can use ES's [scraping](http://en.wikipedia.org/wiki/Web_scraping) tools to avoid creating a gamelist.xml by hand.* There are two ways to run the scraper: - -* **If you want to scrape multiple games:** press start to open the menu and choose the "SCRAPER" option. Adjust your settings and press "SCRAPE NOW". -* **If you just want to scrape one game:** find the game on the game list in ES and press select. Choose "EDIT THIS GAME'S METADATA" and then press the "SCRAPE" button at the bottom of the metadata editor. - -You can also edit metadata within ES by using the metadata editor - just find the game you wish to edit on the gamelist, press Select, and choose "EDIT THIS GAME'S METADATA." - -A command-line version of the scraper is also provided - just run emulationstation with `--scrape` *(currently broken)*. - -The switch `--ignore-gamelist` can be used to ignore the gamelist and force ES to use the non-detailed view. - -If you're writing a tool to generate or parse gamelist.xml files, you should check out [GAMELISTS.md](GAMELISTS.md) for more detailed documentation. - - -Themes -====== - -By default, EmulationStation looks pretty ugly. You can fix that. If you want to know more about making your own themes (or editing existing ones), read [THEMES.md](THEMES.md)! - -I've put some themes up for download on my EmulationStation webpage: http://aloshi.com/emulationstation#themes - -If you're using RetroPie, you should already have a nice set of themes automatically installed! - - --Alec "Aloshi" Lofquist -http://www.aloshi.com -http://www.emulationstation.org +--home Force the .emulationstation folder (windows) +--help, -h summon a sentient, angry tuba +``` + +As long as ES hasn't frozen, you can always press F4 to close the application. + + +Writing an es_systems.cfg +========================= + +Complete configuration instructions at [emulationstation.org](http://emulationstation.org/gettingstarted.html#config). + +The `es_systems.cfg` file contains the system configuration data for EmulationStation, written in XML. This tells EmulationStation what systems you have, what platform they correspond to (for scraping), and where the games are located. + +ES will check two places for an es_systems.cfg file, in the following order, stopping after it finds one that works: +* `~/.emulationstation/es_systems.cfg` +* `/etc/emulationstation/es_systems.cfg` + +The order EmulationStation displays systems reflects the order you define them in. + +**NOTE:** A system *must* have at least one game present in its "path" directory, or ES will ignore it! If no valid systems are found, ES will report an error and quit! + + + +See [SYSTEMS.md](SYSTEMS.md) for some live examples in EmulationStation. + + + +The following "tags" are replaced by ES in launch commands: + +`%ROM%` - Replaced with absolute path to the selected ROM, with most Bash special characters escaped with a backslash. + +`%BASENAME%` - Replaced with the "base" name of the path to the selected ROM. For example, a path of "/foo/bar.rom", this tag would be "bar". This tag is useful for setting up AdvanceMAME. + +`%ROM_RAW%` - Replaced with the unescaped, absolute path to the selected ROM. If your emulator is picky about paths, you might want to use this instead of %ROM%, but enclosed in quotes. + +`%HOME%` - Replaced with the home folder. + +`%SYSTEM%` - Replaced with the current selected system name. + +`%EMULATOR%` - Replaced with the current selected emulator. + +`%CORE%` - Replaced with the current selected core. + +gamelist.xml +============ + +The gamelist.xml file for a system defines metadata for games, such as a name, image (like a screenshot or box art), description, release date, and rating. + +If at least one game in a system has an image specified, ES will use the detailed view for that system (which displays metadata alongside the game list). + +*You can use ES's [scraping](http://en.wikipedia.org/wiki/Web_scraping) tools to avoid creating a gamelist.xml by hand.* There are two ways to run the scraper: + +* **If you want to scrape multiple games:** press start to open the menu and choose the "SCRAPER" option. Adjust your settings and press "SCRAPE NOW". +* **If you just want to scrape one game:** find the game on the game list in ES and press select. Choose "EDIT THIS GAME'S METADATA" and then press the "SCRAPE" button at the bottom of the metadata editor. + +You can also edit metadata within ES by using the metadata editor - just find the game you wish to edit on the gamelist, press Select, and choose "EDIT THIS GAME'S METADATA." + +A command-line version of the scraper is also provided - just run emulationstation with `--scrape` *(currently broken)*. + +The switch `--ignore-gamelist` can be used to ignore the gamelist and force ES to use the non-detailed view. + +If you're writing a tool to generate or parse gamelist.xml files, you should check out [GAMELISTS.md](GAMELISTS.md) for more detailed documentation. + + +Themes +====== + +By default, EmulationStation looks pretty ugly. You can fix that. If you want to know more about making your own themes (or editing existing ones), read [THEMES.md](THEMES.md)! + diff --git a/THEMES.md b/THEMES.md index c10b2e57d..bead27620 100644 --- a/THEMES.md +++ b/THEMES.md @@ -6,7 +6,7 @@ EmulationStation allows each system to have its own "theme." A theme is a collec The first place ES will check for a theme is in the system's `` folder, for a theme.xml file: * `[SYSTEM_PATH]/theme.xml` -If that file doesn't exist, ES will try to find the theme in the current **theme set**. Theme sets are just a collection of individual system themes arranged in the "themes" folder under some name. A theme set can provide a default theme that will be used if there is no matching system theme. Here's an example: +If that file doesn't exist, ES will try to find the theme in the current **theme set**. Theme sets are just a collection of individual system themes arranged in the "themes" folder under some name. A theme set can provide a default theme that will be used if there is no matching system theme. Here are examples : ``` ... @@ -15,26 +15,36 @@ If that file doesn't exist, ES will try to find the theme in the current **theme snes/ theme.xml my_cool_background.jpg - nes/ theme.xml my_other_super_cool_background.jpg - common_resources/ scroll_sound.wav theme.xml (Default theme) +... another_theme_set/ - snes/ - theme.xml - some_resource.svg + resources/ + snes-logo.svg + snes-back.jpg + nes-logo.svg + nes-back.jpg + theme.xml (Default theme) ``` The theme set system makes it easy for users to try different themes and allows distributions to include multiple theme options. Users can change the currently active theme set in the "UI Settings" menu. The option is only visible if at least one theme set exists. -There are two places ES can load theme sets from: +There are places where ES can load theme sets from: + +Windows : + * `[HOME]/.emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml` -* `/etc/emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml` +* `[HOME]/.emulationstation/themes/[CURRENT_THEME_SET]/theme.xml` + +Linux : + +* `/userdata/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml` +* `/userdata/themes/[CURRENT_THEME_SET]/theme.xml` `[SYSTEM_THEME]` is the `` tag for the system, as defined in `es_systems.cfg`. If the `` tag is not set, ES will use the system's ``. @@ -49,7 +59,7 @@ Here is a very simple theme that changes the description text's color: ```xml - 3 + 4 00FF00 @@ -69,11 +79,11 @@ How it works Everything must be inside a `` tag. -**The `` tag *must* be specified**. This is the version of the theming system the theme was designed for. The current version is 3. +**The `` tag *must* be specified**. This is the version of the theming system the theme was designed for. +The current version is 4. - -A *view* can be thought of as a particular "screen" within EmulationStation. Views are defined like this: +A *view* can be thought of as a particular "display" within EmulationStation. Views are defined like this: ```xml @@ -111,20 +121,35 @@ Or, you can create your own elements by adding `extra="true"` (as is done in the +** BATOCERA 5.24 : + +A *customView* can be thought of as a custom "gamelist view" within EmulationStation. +Custom Views must inherit one of the standard views (basic, detailed, video or grid) or inherit from another custom view. Custom view inherit every element, attribute and behaviour of its parent view, so only differences or changes are needed. + +It is defined like this : + +```xml + + ... define elements here ... + +``` + + Advanced Features ================= -It is recommended that if you are writing a theme you launch EmulationStation with the `--debug` and `--windowed` switches. This way you can read error messages without having to check the log file. You can also reload the current gamelist view and system view with `Ctrl-R` if `--debug` is specified. +It is recommended that if you are writing a theme you launch EmulationStation with the `--windowed` switches. This way you can read error messages without having to check the log file. You can also reload the current gamelist view and system view with `F5` ### The `` tag You can include theme files within theme files, similar to `#include` in C (though the internal mechanism is different, the effect is the same). Example: `~/.emulationstation/all_themes.xml`: + ```xml - 3 + 4 ./all_themes/myfont.ttf @@ -135,9 +160,10 @@ You can include theme files within theme files, similar to `#include` in C (thou ``` `~/.emulationstation/snes/theme.xml`: + ```xml - 3 + 4 ./../all_themes.xml @@ -150,7 +176,7 @@ You can include theme files within theme files, similar to `#include` in C (thou Is equivalent to this `snes/theme.xml`: ```xml - 3 + 4 ./all_themes/myfont.ttf @@ -162,54 +188,70 @@ Is equivalent to this `snes/theme.xml`: Notice that properties that were not specified got merged (``) and the `snes/theme.xml` could overwrite the included files' values (``). Also notice the included file still needed the `` tag. +### Subsets : Create theme variations declaring subsets +** Batocera 5.24 + +Subset are usefull to create multiple variations in a theme ( colorsets, iconsets, different system views...) + +When a subset is defined, you can choose one of the named elements in the subset. Only one is active at a time. Only the active item is included, the other includes of the same subset are ignored. + +"name" attribute must be unique among all includes. + +Common subsets are "colorset", "iconset", "menu", "systemview" or "gamelistview", but you can also add your custom subset names. + +```xml + + ./../nice_colors.xml + ./../other_colors.xml + + ./../nice_sys.xml + ./../carousel.xml + + ./../choice1.xml + ./../choice2.xml + +``` ### Theming multiple views simultaneously Sometimes you want to apply the same properties to the same elements across multiple views. The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas). So, for example, to easily apply the same header to the basic, grid, and system views: ```xml - - 3 - - - ./snes_art/snes_header.png - - - - - ./snes_art/snes_header_detailed.png - - - + + + ./snes_art/snes_header.png + + + + + ./snes_art/snes_header_detailed.png + + ``` This is equivalent to: ```xml - - 3 - - - ./snes_art/snes_header.png - - - - - ./snes_art/snes_header_detailed.png - - - - - ./snes_art/snes_header.png - - - - - ./snes_art/snes_header.png - - - ... and any other view that might try to look up "logo" ... - + + + ./snes_art/snes_header.png + + + + + ./snes_art/snes_header_detailed.png + + + + + ./snes_art/snes_header.png + + + + + ./snes_art/snes_header.png + + ``` @@ -223,8 +265,7 @@ You can theme multiple elements *of the same type* simultaneously. The `name` a 3 - + 48474D @@ -272,7 +313,16 @@ You can now change the order in which elements are rendered by setting `zIndex` #### Defaults +##### screen + +** Batocera 5.24 + +* `text name="clock"` - 10 ( customize the clock ) +* `controllerActivity name="controllerActivity"` - 10 ( customize the connected joystick indicators +* Extra Elements `extra="true"` - 10 + ##### system + * Extra Elements `extra="true"` - 10 * `carousel name="systemcarousel"` - 40 * `text name="systemInfo"` - 50 @@ -284,7 +334,7 @@ You can now change the order in which elements are rendered by setting `zIndex` * `imagegrid name="gamegrid"` - 20 * Media * `image name="md_image"` - 30 - * `video name="md_video"` - 30 + * `video name="md_video"` - 31 * `image name="md_marquee"` - 35 * Metadata - 40 * Labels @@ -323,10 +373,11 @@ System variables are system specific and are derived from the values in es_syste * `system.name` * `system.fullName` * `system.theme` +* `lang` ** Batocera 5.24 #### Theme Defined Variables Variables can also be defined in the theme. -``` +```xml 8b0000 @@ -334,23 +385,65 @@ Variables can also be defined in the theme. #### Usage in themes Variables can be used to specify the value of a theme property: -``` +```xml ${themeColor} ``` or to specify only a portion of the value of a theme property: -``` +```xml ${themeColor}c0 ./art/logo/${system.theme}.svg +./art/logo/${system.theme}-${lang}.svg ```` +### Filter using attributes + +** Batocera 5.24 + +System attributes allow filtering elements and adapt display under conditions : + +* `tinyScreen` - type : BOOL + * Allow elements to be active only with small screens like GPI Case (if true), or disable element with normal screens ( if false ) +* `ifHelpPrompts`- type : BOOL + * Allow elements to be active only if help is visible/invisible in ES menus. +* `lang` - type : STRING + * Allow elements to be used only if the lang is the current language in EmulationStation. + * lang is 2 lower characters. ( fr, br, en, ru, pt.... ) + +#### Usage in themes + +Variables can be used to specify the value of a theme property: + +```xml + + ./gpicase.xml + + + + + 0.950 0.84 + + + + + + Manufacturer + Constructeur + +``` + +or to specify only a portion of the value of a theme property: + + + Reference ========= ## Views, their elements, and themable properties: #### basic + * `helpsystem name="help"` - ALL - The help system style for this view. * `image name="background"` - ALL @@ -366,16 +459,21 @@ Reference #### detailed * `helpsystem name="help"` - ALL + - The help system style for this view. * `image name="background"` - ALL + - This is a background image that exists for convenience. It goes from (0, 0) to (1, 1). * `text name="logoText"` - ALL + - Displays the name of the system. Only present if no "logo" image is specified. Displayed at the top of the screen, centered by default. * `image name="logo"` - ALL + - A header image. If a non-empty `path` is specified, `text name="logoText"` will be hidden and this image will be, by default, displayed roughly in its place. * `textlist name="gamelist"` - ALL - - The gamelist. `primaryColor` is for games, `secondaryColor` is for folders. Left aligned by default. - + +- The gamelist. `primaryColor` is for games, `secondaryColor` is for folders. Left aligned by default. + * Metadata * Labels * `text name="md_lbl_rating"` - ALL @@ -386,12 +484,15 @@ Reference * `text name="md_lbl_players"` - ALL * `text name="md_lbl_lastplayed"` - ALL * `text name="md_lbl_playcount"` - ALL - - * Values +* Values * All values will follow to the right of their labels if a position isn't specified. - - * `image name="md_image"` - POSITION | SIZE | Z_INDEX + + * `image name="md_image"` - POSITION | SIZE | Z_INDEX - Path is the "image" metadata for the currently selected game. + * `video name="md_video"` - POSITION | SIZE | Z_INDEX + - BATOCERA 5.24 : Path is the "video" metadata for the currently selected game. + * `image name="md_marquee"` - POSITION | SIZE | Z_INDEX + - Path is the "marquee" metadata for the currently selected game. * `rating name="md_rating"` - ALL - The "rating" metadata. * `datetime name="md_releasedate"` - ALL @@ -414,6 +515,9 @@ Reference - The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default #### video + +This kind of view is used for retrocompatibility with Retropie themes, but is deprecated. + * `helpsystem name="help"` - ALL - The help system style for this view. * `image name="background"` - ALL @@ -483,7 +587,12 @@ Reference - Note that many of the default gridtile parameters change the selected gridtile parameters if they are not explicitly set by the theme. For example, changing the background image of the default gridtile also change the background image of the selected gridtile. Refer to the gridtile documentation for more informations. * `gridtile name="selected"` - ALL - See default gridtile description right above. - +* `text name="gridtile"` - ALL + - BATOCERA 5.24 : Describes the text label in the grid. See default text description right above +* `text name="gridtile_selected"` - ALL + - BATOCERA 5.24 : Describes the text label in the grid when the gridtile is selected. +* `image name="gridtile.marquee"` - ALL + - BATOCERA 5.24 : Describes the image to use in the grid as a marquee / wheel image. * Metadata * Labels * `text name="md_lbl_rating"` - ALL @@ -534,10 +643,44 @@ Reference - Displays details of the system currently selected in the carousel. * You can use extra elements (elements with `extra="true"`) to add your own backgrounds, etc. They will be displayed behind the carousel, and scroll relative to the carousel. +#### menu +* `helpsystem name="help"` - ALL + - The help system style for this view. If not defined, menus will have the same helpsystem as defined in system view. +* `menuBackground name="menubg"` - COLOR | PATH | FADEPATH + - The background behind menus. you can set an image and/or change color (alpha supported) + +* `menuSwitch name="menuswitch"` - PATHON | PATHOFF + - Images for the on/off switch in menus +* `menuSlider name="menuslider"` - PATH + - Image for the slider knob in menus +* `menuButton name="menubutton"` - PATH | FILLEDPATH + - Images for menu buttons +* `menuText name="menutext"` - FONTPATH | FONTSIZE | COLOR + - text for all menu entries +* `menuText name="menutitle"` - FONTPATH | FONTSIZE | COLOR + - text for menu titles +* `menuText name="menufooter"` - FONTPATH | FONTSIZE | COLOR + - text for menu footers or subtitles +* `menuTextSmall name="menutextsmall"` - FONTPATH | FONTSIZE | COLOR + - text for menu entries in smallerfont + + +menu is used to theme helpsystem and ES menus. + +#### screen + +** BATOCERA 5.24 + +screen is a fixed view and has no themable properties. + +It is used to work like an OSD, to display elements like clock and controllers activity. + +It can also contain text, image and video extras. ## Types of properties: * NORMALIZED_PAIR - two decimals, in the range [0..1], delimited by a space. For example, `0.25 0.5`. Most commonly used for position (x and y coordinates) and size (width and height). +* NORMALIZED_RECT - four decimals, in the range [0..1], delimited by a space. For example, `0.25 0.5 0.10 0.30`. Most commonly used for padding to store top, left, bottom and right coordinates. ** BATOCERA 5.24 * PATH - a path. If the first character is a `~`, it will be expanded into the environment variable for the home path (`$HOME` for Linux or `%HOMEPATH%` for Windows). If the first character is a `.`, it will be expanded to the theme file's directory, allowing you to specify resources relative to the theme file, like so: `./../general_art/myfont.ttf`. * BOOLEAN - `true`/`1` or `false`/`0`. * COLOR - a hexidecimal RGB or RGBA color (6 or 8 digits). If 6 digits, will assume the alpha channel is `FF` (not transparent). @@ -580,20 +723,61 @@ Can be created as an extra. - If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. * `zIndex` - type: FLOAT. - z-index value for component. Components will be rendered in order of z-index value from low to high. +* `reflexion` - type: NORMALIZED_PAIR. + - BATOCERA 5.24 : table reflexion effect. First item is top position alpha, second is bottom alpha. +* `reflexionOnFrame` ` - type: BOOLEAN + - BATOCERA 5.24 : When the image is scaled maxSize, tells if the table reflexion effect alignment is done on the bottom of the physical image, or on the bottom of the frame ( according to pos/size ) +* `minSize` - type: NORMALIZED_PAIR. + - BATOCERA 5.24 : The image will be resized so that it fits the entire rectangle and maintains its aspect ratio. Some parts of the image may be hidden. Used for tiles. +* `colorEnd` - type: COLOR. + - BATOCERA 5.24 : End color for drawing the image with a gradient. +* `gradientType` - type: STRING. + - BATOCERA 5.24 : Direction of the gradient. Values can be 'horizontal' or 'vertical'. Default is 'vertical' +* `horizontalAlignment` - type: STRING. + - BATOCERA 5.24 : If the image is scaled maxSize, tells the image horizontal alignment. Values can be left, right, and center. Default is center. +* `verticalAlignment` - type: STRING. + - BATOCERA 5.24 : If the image is scaled maxSize, tells the image vertical alignment. Values can be top, bottom, and center. Default is center. +* `flipX` - type: BOOLEAN. + - BATOCERA 5.24 : If true, the image will be flipped horizontally. +* `flipY` - type: BOOLEAN. + - BATOCERA 5.24 : If true, the image will be flipped vertically. +* `visible` - type: BOOLEAN. + - BATOCERA 5.24 : Tells if the element is visible or hidden. + #### imagegrid * `pos` - type: NORMALIZED_PAIR. * `size` - type: NORMALIZED_PAIR. - The size of the grid. Take care the selected tile can go out of the grid size, so don't position the grid too close to another element or the screen border. -* `margin` - type: NORMALIZED_PAIR. +* `margin` - type: NORMALIZED_PAIR. Margin between tiles. * `gameImage` - type: PATH. - The default image used for games which doesn't have an image. * `folderImage` - type: PATH. - The default image used for folders which doesn't have an image. * `scrollDirection` - type: STRING. - `vertical` by default, can also be set to `horizontal`. Not that in `horizontal` mod, the tiles are ordered from top to bottom, then from left to right. - +* `zIndex` - type: FLOAT. + - BATOCERA 5.24: z-index value for component. Components will be rendered in order of z-index value from low to high. + +* `padding` - type: NORMALIZED_RECT. + - BATOCERA 5.24 : Padding for displaying tiles. +* `autoLayout` - type: NORMALIZED_PAIR. + - BATOCERA 5.24 : Number of column and rows in the grid (integer values). +* `autoLayoutSelectedZoom` - type: FLOAT. + - BATOCERA 5.24: Zoom factor to apply when a tile is selected. +* `imageSource` - type: STRING. + - BATOCERA 5.24: Selects the image to display. `thumbnail` by default, can also be set to `image` or `marquee`. +* `showVideoAtDelay` - type: FLOAT. + - BATOCERA 5.24: delay in millseconds to display video, when the tile is selected. +* `scrollSound` - type: STRING. + - BATOCERA 5.24: Path of the sound file to play when the grid selection changes. +* `centerSelection` - type: BOOL. + - BATOCERA 5.24: If true the selection will always be centered in the grid. +* `scrollLoop` - type: BOOL. + - BATOCERA 5.24: If true the grid will loop thoughs elements. If false, when the grid has no more elements, it displays no more items. +* `animateSelection` - type: BOOL. + - BATOCERA 5.24: If true the selection under the image will be moved in an animation. #### gridtile * `size` - type: NORMALIZED_PAIR. @@ -612,9 +796,17 @@ Can be created as an extra. - Set the color of the center part of the ninepatch. The default tile background center color and selected tile background center color have no influence on each others. * `backgroundEdgeColor` - type: COLOR. - Set the color of the edge parts of the ninepatch. The default tile background edge color and selected tile background edge color have no influence on each others. - +* `selectionMode` - type: STRING. + - BATOCERA 5.24: Selects if the background is over the full tile or only the image. `full` by default, can also be set to `image`. +* `imageSizeMode` - type: STRING. + - BATOCERA 5.24: Selects the image sizing mode. `maxSize` by default, can also be set to `minSize` (outer zoom) or `size` (stretch). +* `reflexion` - type: NORMALIZED_PAIR. + - BATOCERA 5.24: table reflexion effect. First item is top position alpha, second is bottom alpha. + #### video +Can be created as an extra. + * `pos` - type: NORMALIZED_PAIR. * `size` - type: NORMALIZED_PAIR. - If only one axis is specified (and the other is zero), the other will be automatically calculated in accordance with the video's aspect ratio. @@ -638,7 +830,13 @@ Can be created as an extra. - If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. * `zIndex` - type: FLOAT. - z-index value for component. Components will be rendered in order of z-index value from low to high. - +* `path` - type: PATH. + - BATOCERA 5.24 : Path to video file if video is an extra. + +* `visible` - type: BOOLEAN. + - BATOCERA 5.24 : Tells if the element is visible or hidden. +* `snapshotSource` - type: STRING. + - BATOCERA 5.24 : Defines which image to show during delay. Values can be image, thumbnail, and marquee. #### text Can be created as an extra. @@ -670,6 +868,20 @@ Can be created as an extra. - If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. * `zIndex` - type: FLOAT. - z-index value for component. Components will be rendered in order of z-index value from low to high. +* `glowColor` - type: COLOR; + - BATOCERA 5.24 : Defines the color of the glow around the text. +* `glowSize` - type: FLOAT. + - BATOCERA 5.24 : Defines the size of the glow around the text. +* `glowOffset` - type: FLOAT. + - BATOCERA 5.24 : Defines the decal of the glow around the text (used for shadow effects). +* `reflexion` - type: NORMALIZED_PAIR. + - BATOCERA 5.24 : table reflexion effect. First item is top position alpha, second is bottom alpha. +* `reflexionOnFrame` ` - type: BOOLEAN + - BATOCERA 5.24 : When the image is scaled maxSize, tells if the table reflexion effect alignment is done on the bottom of the physical image, or on the bottom of the frame ( according to pos/size ) +* `padding` - type: NORMALIZED_RECT. + - BATOCERA 5.24 : Padding for displaying text. +* `visible` - type: BOOLEAN. + - BATOCERA 5.24 : Tells if the element is visible or hidden. #### textlist @@ -705,9 +917,15 @@ Can be created as an extra. * `lineSpacing` - type: FLOAT. Controls the space between lines (as a multiple of font height). Default is 1.5. * `zIndex` - type: FLOAT. - z-index value for component. Components will be rendered in order of z-index value from low to high. +* `selectorColorEnd` - type: NORMALIZED_PAIR. + - BATOCERA 5.24 : Bottom color for the gradient of the "selector bar." +* `selectorGradientType` - type: STRING. + - BATOCERA 5.24 : Type of gradient to apply : horizontal or vertical. Default is vertical #### ninepatch +Can be created as an extra. + * `pos` - type: NORMALIZED_PAIR. * `size` - type: NORMALIZED_PAIR. * `path` - type: PATH. @@ -715,6 +933,14 @@ Can be created as an extra. - If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. * `zIndex` - type: FLOAT. - z-index value for component. Components will be rendered in order of z-index value from low to high. +* `color` - type: COLOR. + - BATOCERA 5.24 : Fill color ( assigns center & edge color ) +* `centerColor` - type: COLOR. + - BATOCERA 5.24 : Color of the center. +* `edgeColor` - type: COLOR. + - BATOCERA 5.24 : Color of the edge. +* `cornerSize` - type: NORMALIZED_PAIR. + - BATOCERA 5.24 : Size of the corners. Default is 32 32. EmulationStation borrows the concept of "nine patches" from Android (or "9-Slices"). Currently the implementation is very simple and hard-coded to only use 48x48px images (16x16px for each "patch"). Check the `data/resources` directory for some examples (button.png, frame.png). @@ -825,7 +1051,119 @@ EmulationStation borrows the concept of "nine patches" from Android (or "9-Slice - Default is 3 * `zIndex` - type: FLOAT. - z-index value for component. Components will be rendered in order of z-index value from low to high. +* `colorEnd` - type: COLOR. + - BATOCERA 5.24 : Color for the end of gradient +* `gradientType` - type: STRING. + - BATOCERA 5.24 : Sets the gradient direction. Accepted values are "horizontal" and "vertical". +* `logoPos` - type: NORMALIZED_PAIR. + - BATOCERA 5.24 : Set the logo position if it is not centered. + +* `systemInfoDelay` - type: FLOAT. + - BATOCERA 5.24 : Sets the amount of time before displaying game count information. Default is 1500 +#### menuText & menuTextSmall -The help system is a special element that displays a context-sensitive list of actions the user can take at any time. You should try and keep the position constant throughout every screen. Keep in mind the "default" settings (including position) are used whenever the user opens a menu. +BATOCERA 5.24 -[*Check out the "official" themes for some more examples!*](http://aloshi.com/emulationstation#themes) +* `color` - type: COLOR. + - Default is 777777FF +* `fontPath` - type: PATH. + - Path to a truetype font (.ttf). +* `fontSize` - type: FLOAT. + - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). Default is 0.085 for menutitle, 0.045 for menutext and 0.035 for menufooter and menutextsmall. +* `separatorColor` - type: COLOR. + - Default is C6C7C6FF. Color of lines that separates menu entries. +* `selectedColor` - type: COLOR. + - Default is FFFFFFFF. Color of text for selected menu entry. +* `selectorColor` - type: COLOR. + - Default is 878787FF. Color of the selector bar. +* `selectorColorEnd` - type: NORMALIZED_PAIR. + - Bottom color for the gradient of the "selector bar." + + +#### menuSwitch + +BATOCERA 5.24 - replace the switch image in menus + +* `pathOn` - type: PATH. + - Image path when the switch is on +* `pathOff` - type: PATH. + - Image path when the switch is off + +#### menuButton + +BATOCERA 5.24 - replace the button images in menus + +* `path` - type: PATH. + - Image path when the button is not selected +* `filledPath` - type: PATH. + - Image path when the button is selected. + +#### menuTextEdit + +BATOCERA 5.24 - replace the textbox background images in OSK + +* `inactive` - type: PATH. + - Image path when the textbox is not selected +* `active` - type: PATH. + - Image path when the textbox is selected. + +#### menuIcons + +BATOCERA 5.24 - Add images to menuitems + +* `*` - type: PATH. + - Element name must be the image name in the list : iconSystem, iconUpdates, iconControllers, iconGames, iconUI, iconSound, iconNetwork, iconScraper, iconAdvanced, iconQuit, iconRetroachievements, iconKodi, iconRestart, iconShutdown, iconFastShutdown + +#### controllerActivity + +BATOCERA 5.24 - controllerActivity element must be defined in screen view + +* `pos` - type: NORMALIZED_PAIR. + +* `size` - type: NORMALIZED_PAIR. + + - Only one value is actually used. The other value should be zero. (e.g. specify width OR height, but not both. This is done to maintain the aspect ratio.) + +* `itemSpacing` - type: FLOAT. + + - Space between controller images + +* `horizontalAlignment` - type: STRING. + + - Image alignment - left, right, center. + +* `imagePath` - type: PATH. + + - Image to use to represent a joystick. + +* `color` - type: COLOR. + + - Default color. + +* `activityColor` - type: COLOR. + + - Color when the joystick has activity + +* `hotkeyColor` - type: COLOR. + + - Color when the joystick hotkey is pressed. + +* `visible` - type: BOOLEAN. + + - Show/Hides the controllers + +* `zIndex` - type: FLOAT. + + - z-index value for component. Components will be rendered in order of z-index value from low to high. + + + + + + + + + + + + \ No newline at end of file