mirror of
https://github.com/RetroDECK/ES-DE.git
synced 2024-11-21 21:55:38 +00:00
Documentation update.
This commit is contained in:
Leon Styhre
parent
406aecc6a9
commit
11f2d2dfa1
|
|
@ -42,7 +42,7 @@
|
|||
* Greatly improved application startup speed by avoiding a lot of unnecessary SVG rasterizations
|
||||
* Added support for texture mipmapping with trilinear filtering
|
||||
* Improved the renderer scaling accuracy
|
||||
* Added a tileSize property to the image element so that the size of each individual image in tiled textures can be defined
|
||||
* Added new tileSize, tileHorizontalAlignment and tileVerticalAlignment properties to the image element for better tiling support
|
||||
* Added support for substituting the emulator binary in staticpath rules with an explicit command (useful for launching specific binaries in Flatpaks)
|
||||
* The actual names for emulators with find rule entries are now displayed in the error popup window if they're not found during game launch
|
||||
* Reorganized the UI Settings menu a bit and added entries to set the variant and aspect ratio for newer theme sets
|
||||
|
|
|
|||
|
|
@ -1895,7 +1895,9 @@ Just make sure to not place the portable installation on a network share that us
|
|||
|
||||
There are numerous locations throughout ES-DE where custom scripts can be executed if the option to do so has been enabled in the settings. You'll find the option _Enable custom event scripts_ on the Main menu under _Other settings_. By default this setting is deactivated so make sure to enable it to use this feature.
|
||||
|
||||
The approach is quite straightforward, ES-DE will look for any files inside a script directory that corresponds to the event that is triggered and will then execute all these files. There are up to four parameters that will be passed to these scripts, as detailed below:
|
||||
The approach is quite straightforward, ES-DE will look for any files inside a script directory that corresponds to the event that is triggered and will then execute all these files. If you want to have the scripts executed in a certain order you can name them accordingly as they will be sorted and executed in lexicographic order. The sorting is case-sensitive on Unix/Linux and case-insensitive on macOS and Windows. ES-DE will wait for each script to finish its execution before moving on to the next one, so the application will suspend briefly when whatever the script is doing is executing. If you want to avoid this you can setup a wrapper script that executes another script outside the ES-DE scripts directory as a background process.
|
||||
|
||||
There are up to four parameters that will be passed to these scripts, as detailed below:
|
||||
|
||||
| Event | Parameters* | Description |
|
||||
| :----------------------- | :------------------------------------------------- | :-------------------------------------------------------------------------- |
|
||||
|
|
|
|||
|
|
@ -241,7 +241,7 @@ For more serious issues where it does not make sense to assign a default value o
|
|||
Jan 28 17:29:11 Error: VideoComponent: Invalid theme configuration, property <imageType> defined as "covr"
|
||||
```
|
||||
|
||||
### Variants
|
||||
## Variants
|
||||
|
||||
A core concept of ES-DE is the use of theme set _variants_ to provide different theme profiles. These are not fixed presets and a theme author can instead name and define whatever variants he wants for his theme (or possibly use no variants at all as they are optional).
|
||||
|
||||
|
|
@ -314,7 +314,7 @@ Here are some example uses of the `<variant>` functionality:
|
|||
</theme>
|
||||
```
|
||||
|
||||
### Aspect ratios
|
||||
## Aspect ratios
|
||||
|
||||
The aspect ratio support works almost identically to the variants support with the main difference that the available aspect ratios are hardcoded into ES-DE. The theme set can still decide which of the aspect ratios to support (or none at all in which cast the theme aspect ratios is left undefined) but it can't create entirely new aspect ratios.
|
||||
|
||||
|
|
@ -376,7 +376,7 @@ Once the aspect ratios have been defined, they are applied to the theme configur
|
|||
</theme>
|
||||
```
|
||||
|
||||
### capabilities.xml
|
||||
## capabilities.xml
|
||||
|
||||
Variant and aspect ratio values need to be declared before they can be used inside the actual theme set configuration files and that is done in the `capabilities.xml` file. This file needs to exist in the root of the theme directory, for example:
|
||||
```
|
||||
|
|
@ -429,7 +429,7 @@ The declared aspect ratios will always get displayed in the _UI settings_ menu i
|
|||
|
||||
The use of variants and aspect ratios is optional, i.e. a theme set does not need to provide either of them. There must however be a capabilities.xml file present in the root of the theme set directory. So if you don't wish to provide this functionality, simply create an empty file or perhaps add a short XML comment to it to clarify that the theme set does not provide this functionality. In this case the theme will still load and work correctly but the menu options for selecting variants and aspect ratios will be grayed out.
|
||||
|
||||
### The \<include\> tag
|
||||
## The \<include\> tag
|
||||
|
||||
You can include theme files within theme files, for example:
|
||||
|
||||
|
|
@ -536,7 +536,7 @@ You can add `<include>` tags directly inside the `<theme>` tags or inside either
|
|||
</theme>
|
||||
```
|
||||
|
||||
### Theming the system and gamelist views simultaneously
|
||||
## Theming the system and gamelist views simultaneously
|
||||
|
||||
Sometimes you may want to apply the same elements and properties to both the system and gamelist views, for instance defining a common background image. For these situations both views can simply be defined in the `name` attribute. The values can be separated by a comma, or by a whitespace character (tab, space or line break).
|
||||
|
||||
|
|
@ -577,7 +577,7 @@ The above is equivalent to:
|
|||
</view>
|
||||
```
|
||||
|
||||
### Theming multiple elements simultaneously
|
||||
## Theming multiple elements simultaneously
|
||||
|
||||
You can theme multiple elements of the same type simultaneously, which can lead to a more compact and easier to understand theme configuration. To accomplish this you simply define multiple entries inside a single `name` attribute, separated by commas or whitespace characters (tabs, spaces or line breaks).
|
||||
|
||||
|
|
@ -631,7 +631,7 @@ The above is equivalent to:
|
|||
Just remember, _this only works if the elements have the same type._
|
||||
|
||||
|
||||
### Navigation sounds
|
||||
## Navigation sounds
|
||||
|
||||
Navigation sounds are configured globally per theme set, so it needs to be defined using the special `all` view.
|
||||
It's recommended to put these elements in a separate file and include it from the main theme file (e.g. `<include>./navigationsounds.xml</include>`). Starting ES-DE with the --debug flag will provide feedback on whether any navigation sound elements were read from the theme set. If no navigation sounds are provided by the theme, ES-DE will use the bundled navigation sounds as a fallback. This is done per sound file, so the theme could provide for example one or two custom sounds while using the bundled ES-DE sounds for the rest.
|
||||
|
|
@ -675,7 +675,7 @@ Example `navigationsounds.xml` file:
|
|||
</theme>
|
||||
```
|
||||
|
||||
### Element rendering order using zIndex
|
||||
## Element rendering order using zIndex
|
||||
|
||||
You can change the order in which elements are rendered by setting their `zIndex` values. All elements have a default value so you only need to define it for the ones you wish to explicitly change. Elements will be rendered in order from smallest to largest values. A complete description of each element including all supported properties can be found in the [Reference](THEMES-DEV.md#reference) section.
|
||||
|
||||
|
|
@ -696,13 +696,13 @@ These are the default zIndex values per element type:
|
|||
|
||||
The `helpsystem` element does not really have a zIndex value and is always rendered on top of all other elements.
|
||||
|
||||
### Theme variables
|
||||
## Theme variables
|
||||
|
||||
Theme variables can be used to simplify theme construction. There are 2 types of variables available.
|
||||
* System variables
|
||||
* Theme defined variables
|
||||
|
||||
#### System variables
|
||||
### System variables
|
||||
|
||||
System variables are system specific and are derived from the values in es_systems.xml (except for collections).
|
||||
* `system.name`
|
||||
|
|
@ -715,7 +715,7 @@ System variables are system specific and are derived from the values in es_syste
|
|||
* `system.theme.collections`
|
||||
* `system.theme.noCollections`
|
||||
|
||||
#### Theme defined variables
|
||||
### Theme defined variables
|
||||
Variables can also be defined in the theme.
|
||||
```
|
||||
<variables>
|
||||
|
|
@ -723,7 +723,7 @@ Variables can also be defined in the theme.
|
|||
</variables>
|
||||
```
|
||||
|
||||
#### Usage in themes
|
||||
### Usage in themes
|
||||
Variables can be used to specify the value of a theme property:
|
||||
```
|
||||
<color>${themeColor}</color>
|
||||
|
|
@ -779,7 +779,7 @@ Instances per view:
|
|||
Properties:
|
||||
* `pos` - type: NORMALIZED_PAIR
|
||||
* `size` - type: NORMALIZED_PAIR
|
||||
- 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 the size will be clamped to `0.001 0.001` in this case. If scaling SVG images to non-standard aspect ratios, then 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 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 the size will be clamped to `0.001 0.001` 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.
|
||||
- Minimum value per axis is `0.001` and maximum value per axis is `3`. If specifying a value outside the allowed range then no attempt will be made to preserve the aspect ratio.
|
||||
* `maxSize` - type: NORMALIZED_PAIR
|
||||
- The image will be resized as large as possible so that it fits within this size while maintaining its aspect ratio. Use this instead of `size` when you don't know what kind of image you're using so it doesn't get grossly oversized on one axis (e.g. with a game's image metadata). Although this property is possible to combine with the `tile` property that does not make a whole lot of sense, instead use the `size` property for tiled images.
|
||||
|
|
@ -819,10 +819,18 @@ Properties:
|
|||
* `tile` - type: BOOLEAN
|
||||
- If true, the image will be tiled instead of stretched to fit its size. Useful for backgrounds.
|
||||
* `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, then 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. Be aware that tiles are built from the bottom left corner rather than from the upper left corner so make sure to set this property accordingly so the texture alignment is correct.
|
||||
- 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`.
|
||||
* `tileHorizontalAlignment` - type: STRING
|
||||
- If the images making up the tiled texture do not match precisely with the edges of the overall element, then this property can be used to define the alignment on the horizontal axis.
|
||||
- Valid values are `left` or `right`
|
||||
- Default is `left`
|
||||
* `tileVerticalAlignment` - type: STRING
|
||||
- If the images making up the tiled texture do not match precisely with the edges of the overall element, then this property can be used to define the alignment on the vertical axis.
|
||||
- Valid values are `top` or `bottom`
|
||||
- Default is `top`
|
||||
* `interpolation` - type: STRING
|
||||
- Interpolation method to use when scaling. Nearest neighbor (`nearest`) preserves sharp pixels and linear filtering (`linear`) makes the image smoother. This property has limited effect on scalable vector graphics (SVG) images unless the image is stretched or squashed using the `size` property.
|
||||
- Interpolation method to use when scaling. Nearest neighbor (`nearest`) preserves sharp pixels and linear filtering (`linear`) makes the image smoother. This property has limited effect on scalable vector graphics (SVG) images unless the image is stretched or squashed using the `size` property, or if rotation is applied.
|
||||
- Valid values are `nearest` or `linear`
|
||||
- Default is `nearest`
|
||||
* `color` - type: COLOR
|
||||
|
|
|
|||
Loading…
Reference in a new issue