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

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2022-04-12 19:09:34 +02:00
parent 963834afec
commit d7e46205c1
5 changed files with 165 additions and 152 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
CHANGELOG.md
View file

@ -14,7 +14,7 @@
* Added theme support for defining and applying different layouts for various display aspect ratios such as 16:9 and 4:3 * Added theme support for defining and applying different layouts for various display aspect ratios such as 16:9 and 4:3
* Made gamelist theming much more flexible by allowing any number of elements of any types to be defined * Made gamelist theming much more flexible by allowing any number of elements of any types to be defined
* Deprecated multiple older theming concepts like features, extras and hardcoded metadata attributes * Deprecated multiple older theming concepts like features, extras and hardcoded metadata attributes
* Added support for launching game files inside folders without having to enter the folder * Added support for folder links, used for launching game files inside folders without having to enter them
* Modernized the OpenGL renderer by replacing the fixed function pipeline with shaders * Modernized the OpenGL renderer by replacing the fixed function pipeline with shaders
* Unified the desktop OpenGL and OpenGL ES renderers and upgraded to OpenGL 3.3 (as default) and OpenGL ES 3.0 respectively * Unified the desktop OpenGL and OpenGL ES renderers and upgraded to OpenGL 3.3 (as default) and OpenGL ES 3.0 respectively
* OpenGL: Added an OpenGLVersion setting for choosing between OpenGL 3.3, 4.2 and 4.6 (has to be manually set in es_settings.xml) * OpenGL: Added an OpenGLVersion setting for choosing between OpenGL 3.3, 4.2 and 4.6 (has to be manually set in es_settings.xml)

3
INSTALL-DEV.md
View file

@ -1676,7 +1676,8 @@ For folders, most of the fields are identical although some are removed. In the
* `nomultiscrape` * `nomultiscrape`
* `hidemetadata` * `hidemetadata`
* `controller` * `controller`
* `lastplayed` - statistic, for folders this is inherited by the latest game file launched inside the folder. * `folderlink` - string, points to a file inside the game's folder structure that will be launched instead of entering the folder
* `lastplayed` - statistic, datetime, for folders this is inherited by the latest game file launched inside the folder.
**Additional gamelist.xml information** **Additional gamelist.xml information**

124
THEMES-DEV.md
View file

@ -12,6 +12,8 @@ Table of contents:
ES-DE allows the grouping of themes for multiple game systems into a **theme set**. A theme is a collection of **elements**, each with their own **properties** that define the way they look and behave. These elements include things like text lists, carousels, images and animations. ES-DE allows the grouping of themes for multiple game systems into a **theme set**. A theme is a collection of **elements**, each with their own **properties** that define the way they look and behave. These elements include things like text lists, carousels, images and animations.
Internally ES-DE uses the concept of **components** to actually implement the necessary building blocks to parse and render the elements, and although this is normally beyond the scope of what a theme author needs to consider, it's still good to be aware of the term as it's sometimes used in the documentation.
Every game system has its own subdirectory within the theme set directory structure, and these are defined in the systems configuration file `es_systems.xml` either via the optional `<theme>` tag, or otherwise via the mandatory `<name>` tag. When ES-DE populates a system on startup it will look for a file named `theme.xml` in each such directory. Every game system has its own subdirectory within the theme set directory structure, and these are defined in the systems configuration file `es_systems.xml` either via the optional `<theme>` tag, or otherwise via the mandatory `<name>` tag. When ES-DE populates a system on startup it will look for a file named `theme.xml` in each such directory.
By placing a theme.xml file directly in the root of the theme set directory, that file will be processed as a default if there is no system-specific theme.xml file available. By placing a theme.xml file directly in the root of the theme set directory, that file will be processed as a default if there is no system-specific theme.xml file available.
@ -78,7 +80,7 @@ The following are the most important changes compared to the legacy theme struct
* The concept of _features_ is gone * The concept of _features_ is gone
* The `<formatVersion>` tag is gone as tracking theme versions doesn't make much sense after all * The `<formatVersion>` tag is gone as tracking theme versions doesn't make much sense after all
* The `video` element properties `showSnapshotNoVideo` and `showSnapshotDelay` have been removed * The `video` element properties `showSnapshotNoVideo` and `showSnapshotDelay` have been removed
* The ambiguous `alignment` property has been replaced with the `horizontalAlignment` and `verticalAlignment` properties (the same is true for `logoAlignment` for the `carousel` component) * The ambiguous `alignment` property has been replaced with the `horizontalAlignment` and `verticalAlignment` properties (the same is true for `logoAlignment` for the `carousel` element)
* The `forceUppercase` property has been replaced with the more versatile `letterCase` property * The `forceUppercase` property has been replaced with the more versatile `letterCase` property
* The carousel text element hacks `systemInfo` and `logoText` have been removed and replaced with proper carousel properties * The carousel text element hacks `systemInfo` and `logoText` have been removed and replaced with proper carousel properties
* The carousel property maxLogoCount is now in float format for more granular control of logo placement compared to integer format for legacy themes. However some legacy theme authors thought this property supported floats (as the theme documentation incorrectly stated this) and have therefore set it to fractional values such as 3.5. This was actually rounded up when loading the theme configuration, and this logic is retained for legacy themes for backward compatibility. But for current themes the float value is correctly interpreted which means a manual rounding of the value is required in order to retain an identical layout when porting theme sets to the new theme engine * The carousel property maxLogoCount is now in float format for more granular control of logo placement compared to integer format for legacy themes. However some legacy theme authors thought this property supported floats (as the theme documentation incorrectly stated this) and have therefore set it to fractional values such as 3.5. This was actually rounded up when loading the theme configuration, and this logic is retained for legacy themes for backward compatibility. But for current themes the float value is correctly interpreted which means a manual rounding of the value is required in order to retain an identical layout when porting theme sets to the new theme engine
@ -135,8 +137,8 @@ This is the element structure:
</ElementTypeHere> </ElementTypeHere>
``` ```
Finally _properties_ control how a particular element looks and behaves, for example its position, size, image path, animation controls etc. The property type determines what kinds of values you can use. You can read about each type below in the Finally _properties_ control how a particular element looks and behaves, for example its position, size, image path, animation controls etc. The property type determines what kinds of values you can use. You can read about each type below in the
[Reference](THEMES-DEV.md#reference) section. Properties are defined like this: [Reference](THEMES-DEV.md#reference) section. Properties are defined like this:
```xml ```xml
<propertyNameHere>ValueHere</propertyNameHere> <propertyNameHere>ValueHere</propertyNameHere>
@ -214,7 +216,7 @@ In addition to this, if the name is used for the same element type but for diffe
## Debugging during theme development ## Debugging during theme development
If you are writing a theme it's recommended to launch ES-DE with the `--debug` flag from a terminal window. You can also pass the `--resolution` flag to avoid having the application window fill the entire screen. By doing so, you can read error messages directly in the terminal window without having to open the es_log.txt file. You can also reload the current gamelist or system view with `Ctrl+r` if the `--debug` flag has been set. There is also support for highlighting the size and position of each image and animation element by using the `Ctrl+i` key combination and likewise to highlight each text element by using the `Ctrl+t` keys. Again, both of these require that ES-DE has been launched with the `--debug` command line option, for example: If you are writing a theme it's recommended to launch ES-DE with the `--debug` flag from a terminal window. You can also pass the `--resolution` flag to avoid having the application window fill the entire screen. By doing so, you can read error messages directly in the terminal window without having to open the es_log.txt file. You can also reload the current gamelist or system view with `Ctrl+r` if the `--debug` flag has been set. There is also support for highlighting the size and position of each image and animation element by using the `Ctrl+i` key combination and likewise to highlight each text element by using the `Ctrl+t` keys. Again, both of these require that ES-DE has been launched with the `--debug` command line option, for example:
``` ```
emulationstation --debug --resolution 1280 720 emulationstation --debug --resolution 1280 720
``` ```
@ -235,7 +237,7 @@ Note however that warnings are not printed for all invalid properties as that wo
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). 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).
The variants could be purely cosmetic, such as providing light and dark mode versions of the theme set, or they could provide different functionality by for instance using different primary components such as a carousel or a text list. The variants could be purely cosmetic, such as providing light and dark mode versions of the theme set, or they could provide different functionality by for instance using different primary elements such as a carousel or a text list.
Before a variant can be used it needs to be declared, which is done in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detailed later in this document. Before a variant can be used it needs to be declared, which is done in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detailed later in this document.
@ -688,7 +690,7 @@ The `helpsystem` element does not really have a zIndex value and is always rende
### Theme variables ### Theme variables
Theme variables can be used to simplify theme construction. There are 2 types of variables available. Theme variables can be used to simplify theme construction. There are 2 types of variables available.
* System variables * System variables
* Theme defined variables * Theme defined variables
@ -740,18 +742,18 @@ This section describes each element and their properties in detail and also cont
### Property data types ### Property data types
* 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_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. * 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.
* PATH - a path. If the first character is a `~`, it will be expanded into the environment variable for the home path (`$HOME` for Unix and macOS or `%HOMEPATH%` for Windows) unless overridden using the --home command line option. 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: `./../core/fonts/myfont.ttf`. * PATH - a path. If the first character is a `~`, it will be expanded into the environment variable for the home path (`$HOME` for Unix and macOS or `%HOMEPATH%` for Windows) unless overridden using the --home command line option. f 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: `./../core/fonts/myfont.ttf`.
* BOOLEAN - `true`/`1` or `false`/`0`. * 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` (completely opaque). * COLOR - a hexadecimal RGB or RGBA color (6 or 8 digits). If 6 digits, will assume the alpha channel is `FF` (completely opaque).
* UNSIGNED_INTEGER - an unsigned integer. * UNSIGNED_INTEGER - an unsigned integer.
* FLOAT - a decimal. * FLOAT - a decimal.
* STRING - a string of text. * STRING - a string of text.
### Element types and their properties ### Element types and their properties
Common to almost all elements is a `pos` and `size` property of the NORMALIZED_PAIR type. They are normalized in terms of their "parent" object's size; 99% of the time this is just the size of the screen. In this case, `<pos>0 0</pos>` would correspond to the top left corner, and `<pos>1 1</pos>` the bottom right corner (a positive Y value points further down). You can also use numbers outside of the [0..1] range if you want to place an element partially or completely off-screen. Common to almost all elements is a `pos` and `size` property of the NORMALIZED_PAIR type. They are normalized in terms of their "parent" object's size; 99% of the time this is just the size of the screen. In this case, `<pos>0 0</pos>` would correspond to the top left corner, and `<pos>1 1</pos>` the bottom right corner (a positive Y value points further down). You can also use numbers outside of the [0..1] range if you want to place an element partially or completely off-screen.
The order in which you define properties does not matter and you only need to define the ones where you want to override the default value. The order in which you define properties does not matter and you only need to define the ones where you want to override the default value.
@ -771,19 +773,19 @@ Properties:
* `size` - 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 image's aspect ratio. - If only one axis is specified (and the other is zero), the other will be automatically calculated in accordance with the image's aspect ratio.
* `maxSize` - type: NORMALIZED_PAIR * `maxSize` - type: NORMALIZED_PAIR
- The image will be resized as large as possible so that it fits within this size and maintains 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). - The image will be resized as large as possible so that it fits within this size and maintains 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).
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0.5 0.5` - Default is `0.5 0.5`
* `rotation` - type: FLOAT * `rotation` - type: FLOAT
- Angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - Angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is `0` - Default is `0`
* `rotationOrigin` - type: NORMALIZED_PAIR * `rotationOrigin` - type: NORMALIZED_PAIR
- Point around which the image will be rotated. - Point around which the image will be rotated.
- Default is `0.5 0.5` - Default is `0.5 0.5`
* `path` - type: PATH * `path` - type: PATH
- Explicit path to an image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif). If `imageType` is also defined then this will take precedence as these two properties are not intended to be used together. If you need a fallback image in case of missing game media, use the `default` property instead. - Explicit path to an image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif). If `imageType` is also defined then this will take precedence as these two properties are not intended to be used together. If you need a fallback image in case of missing game media, use the `default` property instead.
* `default` - type: PATH * `default` - type: PATH
- Path to a default image file. The default image will be displayed when the selected game does not have an image of the type defined by the `imageType` property (i.e. this `default` property does nothing unless a valid `imageType` property has been set). It's also applied to any custom collection that does not contain any games when browsing the grouped custom collections system. - Path to a default image file. The default image will be displayed when the selected game does not have an image of the type defined by the `imageType` property (i.e. this `default` property does nothing unless a valid `imageType` property has been set). It's also applied to any custom collection that does not contain any games when browsing the grouped custom collections system.
* `imageType` - type: STRING * `imageType` - type: STRING
@ -801,13 +803,13 @@ Properties:
* `gameselector` - type: STRING * `gameselector` - type: STRING
- If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `imageType` property is utilized. - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `imageType` property is utilized.
* `tile` - type: BOOLEAN * `tile` - type: BOOLEAN
- If true, the image will be tiled instead of stretched to fit its size. Useful for backgrounds. - If true, the image will be tiled instead of stretched to fit its size. Useful for backgrounds.
* `interpolation` - type: STRING * `interpolation` - type: STRING
- Interpolation method to use when scaling raster images. Nearest neighbor (`nearest`) preserves sharp pixels and linear filtering (`linear`) makes the image smoother. This property has no effect on scalable vector graphics (SVG) images. - Interpolation method to use when scaling raster images. Nearest neighbor (`nearest`) preserves sharp pixels and linear filtering (`linear`) makes the image smoother. This property has no effect on scalable vector graphics (SVG) images.
- Valid values are `nearest` or `linear` - Valid values are `nearest` or `linear`
- Default is `nearest` - Default is `nearest`
* `color` - type: COLOR * `color` - type: COLOR
- Multiply each pixel's color by this color. For example, an all-white image with `<color>FF0000</color>` would become completely red. You can also control the transparency of an image with `<color>FFFFFFAA</color>` - keeping all the pixels their normal color and only affecting the alpha channel. - Multiply each pixel's color by this color. For example, an all-white image with `<color>FF0000</color>` would become completely red. You can also control the transparency of an image with `<color>FFFFFFAA</color>` - keeping all the pixels their normal color and only affecting the alpha channel.
* `colorEnd` - type: COLOR * `colorEnd` - type: COLOR
- Works exactly in the same way as `color` but can be set as the end color to apply a color shift gradient to the image. - Works exactly in the same way as `color` but can be set as the end color to apply a color shift gradient to the image.
* `gradientType` - type: STRING * `gradientType` - type: STRING
@ -829,7 +831,7 @@ Properties:
- If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0` - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
- Default is `true` - Default is `true`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `30` - Default is `30`
#### video #### video
@ -848,9 +850,9 @@ Properties:
* `size` - 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. - 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.
* `maxSize` - type: NORMALIZED_PAIR * `maxSize` - type: NORMALIZED_PAIR
- The video will be resized as large as possible so that it fits within this size and maintains its aspect ratio. Use this instead of `size` when you don't know what kind of video you're using so it doesn't get grossly oversized on one axis (e.g. with a game's video metadata). - The video will be resized as large as possible so that it fits within this size and maintains its aspect ratio. Use this instead of `size` when you don't know what kind of video you're using so it doesn't get grossly oversized on one axis (e.g. with a game's video metadata).
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0.5 0.5` - Default is `0.5 0.5`
* `path` - type: PATH * `path` - type: PATH
@ -909,7 +911,7 @@ Properties:
- If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0` - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
- Default is `true` - Default is `true`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `30` - Default is `30`
#### animation #### animation
@ -928,17 +930,17 @@ Properties:
* `size` - 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 animation's aspect ratio. Note that this is sometimes not entirely accurate as some animations contain invalid size information. - If only one axis is specified (and the other is zero), the other will be automatically calculated in accordance with the animation's aspect ratio. Note that this is sometimes not entirely accurate as some animations contain invalid size information.
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0.5 0.5` - Default is `0.5 0.5`
* `rotation` - type: FLOAT * `rotation` - type: FLOAT
- Angle in degrees that the animation should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - Angle in degrees that the animation should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is `0` - Default is `0`
* `rotationOrigin` - type: NORMALIZED_PAIR * `rotationOrigin` - type: NORMALIZED_PAIR
- Point around which the animation will be rotated. - Point around which the animation will be rotated.
- Default is `0.5 0.5` - Default is `0.5 0.5`
* `path` - type: PATH * `path` - type: PATH
- Path to the animation file. Only the .json extension is supported. - Path to the animation file. Only the .json extension is supported.
* `speed` - type: FLOAT. * `speed` - type: FLOAT.
- The relative speed at which to play the animation. - The relative speed at which to play the animation.
- Minimum value is `0.2` and maximum value is `3` - Minimum value is `0.2` and maximum value is `3`
@ -965,7 +967,7 @@ Properties:
- If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0` - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
- Default is `true` - Default is `true`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `35` - Default is `35`
#### badges #### badges
@ -986,11 +988,11 @@ Properties:
- Minimum value per axis is `0.03` and maximum value per axis is `1` - Minimum value per axis is `0.03` and maximum value per axis is `1`
- Default is `0.15 0.20` - Default is `0.15 0.20`
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0.5 0.5` - Default is `0.5 0.5`
* `rotation` - type: FLOAT * `rotation` - type: FLOAT
- Angle in degrees that the badges should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - Angle in degrees that the badges should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is `0` - Default is `0`
* `rotationOrigin` - type: NORMALIZED_PAIR * `rotationOrigin` - type: NORMALIZED_PAIR
- Point around which the image will be rotated. - Point around which the image will be rotated.
@ -1071,7 +1073,7 @@ Properties:
- If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0` - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
- Default is `true` - Default is `true`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `35` - Default is `35`
#### text #### text
@ -1091,13 +1093,13 @@ Properties:
- Possible combinations: - Possible combinations:
- `0 0` - automatically size so text fits on one line (expanding horizontally). - `0 0` - automatically size so text fits on one line (expanding horizontally).
- `w 0` - automatically wrap text so it doesn't go beyond `w` (expanding vertically). - `w 0` - automatically wrap text so it doesn't go beyond `w` (expanding vertically).
- `w h` - works like a "text box." If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...). - `w h` - works like a "text box". If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...).
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0 0` - Default is `0 0`
* `rotation` - type: FLOAT * `rotation` - type: FLOAT
- Angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. Rotation is not possible if the `container` property has been set to true. - Angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. Rotation is not possible if the `container` property has been set to true.
- Default is `0` - Default is `0`
* `rotationOrigin` - type: NORMALIZED_PAIR * `rotationOrigin` - type: NORMALIZED_PAIR
- Point around which the text will be rotated. - Point around which the text will be rotated.
@ -1174,7 +1176,7 @@ Properties:
- If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0` - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
- Default is `true` - Default is `true`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `40` - Default is `40`
#### datetime #### datetime
@ -1194,13 +1196,13 @@ Properties:
- Possible combinations: - Possible combinations:
- `0 0` - automatically size so text fits on one line (expanding horizontally). - `0 0` - automatically size so text fits on one line (expanding horizontally).
- `w 0` - automatically wrap text so it doesn't go beyond `w` (expanding vertically). - `w 0` - automatically wrap text so it doesn't go beyond `w` (expanding vertically).
- `w h` - works like a "text box." If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...). - `w h` - works like a "text box". If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...).
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0 0` - Default is `0 0`
* `rotation` - type: FLOAT * `rotation` - type: FLOAT
- Angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - Angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is `0` - Default is `0`
* `rotationOrigin` - type: NORMALIZED_PAIR * `rotationOrigin` - type: NORMALIZED_PAIR
- Point around which the text will be rotated. - Point around which the text will be rotated.
@ -1251,7 +1253,7 @@ Properties:
- If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0` - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
- Default is `true` - Default is `true`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `40` - Default is `40`
#### gamelistinfo #### gamelistinfo
@ -1270,13 +1272,13 @@ Properties:
- Possible combinations: - Possible combinations:
- `0 0` - automatically size so text fits on one line (expanding horizontally). - `0 0` - automatically size so text fits on one line (expanding horizontally).
- `w 0` - automatically wrap text so it doesn't go beyond `w` (expanding vertically). - `w 0` - automatically wrap text so it doesn't go beyond `w` (expanding vertically).
- `w h` - works like a "text box." If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...). - `w h` - works like a "text box". If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...).
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0 0` - Default is `0 0`
* `rotation` - type: FLOAT * `rotation` - type: FLOAT
- Angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - Angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is `0` - Default is `0`
* `rotationOrigin` - type: NORMALIZED_PAIR * `rotationOrigin` - type: NORMALIZED_PAIR
- Point around which the element will be rotated. - Point around which the element will be rotated.
@ -1303,7 +1305,7 @@ Properties:
- If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0` - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
- Default is `true` - Default is `true`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `45` - Default is `45`
#### rating #### rating
@ -1322,13 +1324,13 @@ Instances per view:
Properties: Properties:
* `pos` - type: NORMALIZED_PAIR * `pos` - type: NORMALIZED_PAIR
* `size` - 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.) - 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.)
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0 0` - Default is `0 0`
* `rotation` - type: FLOAT * `rotation` - type: FLOAT
- Angle in degrees that the rating should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - Angle in degrees that the rating should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
- Default is `0` - Default is `0`
* `rotationOrigin` - type: NORMALIZED_PAIR * `rotationOrigin` - type: NORMALIZED_PAIR
- Point around which the rating will be rotated. - Point around which the rating will be rotated.
@ -1336,11 +1338,11 @@ Properties:
* `gameselector` - type: STRING * `gameselector` - type: STRING
- If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view. - 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.
* `color` - type: COLOR * `color` - type: COLOR
- Multiply each pixel's color by this color. For example, an all-white image with `<color>FF0000</color>` would become completely red. You can also control the transparency of an image with `<color>FFFFFFAA</color>` - keeping all the pixels their normal color and only affecting the alpha channel. - Multiply each pixel's color by this color. For example, an all-white image with `<color>FF0000</color>` would become completely red. You can also control the transparency of an image with `<color>FFFFFFAA</color>` - keeping all the pixels their normal color and only affecting the alpha channel.
* `filledPath` - type: PATH * `filledPath` - type: PATH
- Path to the "filled" rating image. Image must be square (width equals height). - Path to the "filled" rating image. Image must be square (width equals height).
* `unfilledPath` - type: PATH * `unfilledPath` - type: PATH
- Path to the "unfilled" rating image. Image must be square (width equals height). - Path to the "unfilled" rating image. Image must be square (width equals height).
* `opacity` - type: FLOAT * `opacity` - type: FLOAT
- Controls the level of transparency. If set to `0` the element will be disabled. - Controls the level of transparency. If set to `0` the element will be disabled.
- Minimum value is `0` and maximum value is `1` - Minimum value is `0` and maximum value is `1`
@ -1349,7 +1351,7 @@ Properties:
- If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0` - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
- Default is `true` - Default is `true`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `45` - Default is `45`
#### carousel #### carousel
@ -1376,7 +1378,7 @@ Properties:
* `pos` - type: NORMALIZED_PAIR * `pos` - type: NORMALIZED_PAIR
- Default is `0 0.38375` - Default is `0 0.38375`
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the carousel `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the carousel exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Where on the carousel `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the carousel exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0 0` - Default is `0 0`
* `color` - type: COLOR * `color` - type: COLOR
@ -1390,9 +1392,9 @@ Properties:
- Valid values are `horizontal` or `vertical` - Valid values are `horizontal` or `vertical`
- Default is `horizontal` - Default is `horizontal`
* `logo` - type: PATH * `logo` - type: PATH
- Path to the logo image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif). - Path to the logo image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif).
* `defaultLogo` - type: PATH * `defaultLogo` - type: PATH
- Path to the default logo file which will be displayed if the image defined via the `logo` property is not found. Most common extensions are supported (including .jpg, .png, and unanimated .gif). - Path to the default logo file which will be displayed if the image defined via the `logo` property is not found. Most common extensions are supported (including .jpg, .png, and unanimated .gif).
* `logoSize` - type: NORMALIZED_PAIR * `logoSize` - type: NORMALIZED_PAIR
- Minimum value per axis is `0.05` and maximum value per axis is `1` - Minimum value per axis is `0.05` and maximum value per axis is `1`
- Default is `0.25 0.155` - Default is `0.25 0.155`
@ -1401,7 +1403,7 @@ Properties:
- Minimum value is `0.5` and maximum value is `3` - Minimum value is `0.5` and maximum value is `3`
- Default is `1.2` - Default is `1.2`
* `logoRotation` - type: FLOAT * `logoRotation` - type: FLOAT
- Angle in degrees that the logos should be rotated. Value should be positive. - Angle in degrees that the logos should be rotated. Value should be positive.
- This property only applies when `type` is "horizontal_wheel" or "vertical_wheel". - This property only applies when `type` is "horizontal_wheel" or "vertical_wheel".
- Default is `7.5` - Default is `7.5`
* `logoRotationOrigin` - type: NORMALIZED_PAIR * `logoRotationOrigin` - type: NORMALIZED_PAIR
@ -1439,7 +1441,7 @@ Properties:
- Minimum value is `0.5` and maximum value is `3` - Minimum value is `0.5` and maximum value is `3`
- Default is `1.5` - Default is `1.5`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `50` - Default is `50`
#### textlist #### textlist
@ -1457,12 +1459,12 @@ Properties:
* `pos` - type: NORMALIZED_PAIR * `pos` - type: NORMALIZED_PAIR
* `size` - type: NORMALIZED_PAIR * `size` - type: NORMALIZED_PAIR
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the position and size attributes are themeable, origin is implied.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
* `selectorHeight` - type: FLOAT * `selectorHeight` - type: FLOAT
- Height of the "selector bar". - Height of the "selector bar".
* `selectorOffsetY` - type: FLOAT * `selectorOffsetY` - type: FLOAT
- Allows moving of the "selector bar" up or down from its computed position. Useful for fine tuning the position of the "selector bar" relative to the text. - Allows moving of the "selector bar" up or down from its computed position. Useful for fine tuning the position of the "selector bar" relative to the text.
* `selectorColor` - type: COLOR * `selectorColor` - type: COLOR
- Color of the selector bar. - Color of the selector bar.
- Default is `000000FF` - Default is `000000FF`
@ -1480,9 +1482,9 @@ Properties:
* `selectedColor` - type: COLOR * `selectedColor` - type: COLOR
- Color of the highlighted entry text. - Color of the highlighted entry text.
* `primaryColor` - type: COLOR * `primaryColor` - type: COLOR
- Primary color; what this means depends on the text list. For example, for game lists, it is the color of a game. - Primary color; what this means depends on the text list. For example, for game lists, it is the color of a game.
* `secondaryColor` - type: COLOR * `secondaryColor` - type: COLOR
- Secondary color; what this means depends on the text list. For example, for game lists, it is the color of a folder. - Secondary color; what this means depends on the text list. For example, for game lists, it is the color of a folder.
* `fontPath` - type: PATH * `fontPath` - type: PATH
* `fontSize` - type: FLOAT * `fontSize` - type: FLOAT
* `horizontalAlignment` - type: STRING * `horizontalAlignment` - type: STRING
@ -1490,7 +1492,7 @@ Properties:
- Valid values are `left`, `center` or `right` - Valid values are `left`, `center` or `right`
- Default is `left` - Default is `left`
* `horizontalMargin` - type: FLOAT * `horizontalMargin` - type: FLOAT
- Horizontal offset for text from the alignment point. If `horizontalAlignment` is "left", offsets the text to the right. If `horizontalAlignment` is "right", offsets text to the left. No effect if `horizontalAlignment` is "center". Given as a percentage of the element's parent's width (same unit as `size`'s X value). - Horizontal offset for text from the alignment point. If `horizontalAlignment` is "left", offsets the text to the right. If `horizontalAlignment` is "right", offsets text to the left. No effect if `horizontalAlignment` is "center". Given as a percentage of the element's parent's width (same unit as `size`'s X value).
* `letterCase` - type: STRING * `letterCase` - type: STRING
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize` - Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
- Default is `none` (original letter case is retained) - Default is `none` (original letter case is retained)
@ -1499,7 +1501,7 @@ Properties:
- Minimum value is `0.5` and maximum value is `3` - Minimum value is `0.5` and maximum value is `3`
- Default is `1.5` - Default is `1.5`
* `zIndex` - type: FLOAT * `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `50` - Default is `50`
#### gameselector #### gameselector
@ -1539,7 +1541,7 @@ Properties:
* `pos` - type: NORMALIZED_PAIR * `pos` - type: NORMALIZED_PAIR
- Default is `0.012 0.9515` - Default is `0.012 0.9515`
* `origin` - type: NORMALIZED_PAIR * `origin` - type: NORMALIZED_PAIR
- Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen.
- Minimum value per axis is `0` and maximum value per axis is `1` - Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0 0` - Default is `0 0`
* `textColor` - type: COLOR * `textColor` - type: COLOR
@ -1631,11 +1633,11 @@ Deprecated.
* `centerSelection` - type: BOOLEAN. * `centerSelection` - type: BOOLEAN.
- `false` by default, when `true` the selected tile will be locked to the center of the grid. - `false` by default, when `true` the selected tile will be locked to the center of the grid.
* `scrollLoop` - type: BOOLEAN. * `scrollLoop` - type: BOOLEAN.
- `false` by default, when `true` the grid will seamlessly loop around when scrolling reaches the end of the list. Only works when `centerSelection` is `true`. - `false` by default, when `true` the grid will seamlessly loop around when scrolling reaches the end of the list. Only works when `centerSelection` is `true`.
* `animate` - type : BOOLEAN. * `animate` - type : BOOLEAN.
- `true` by default, when `false` the grid scrolling will not be animated. - `true` by default, when `false` the grid scrolling will not be animated.
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for element. Elements will be rendered in order of zIndex value from low to high. - z-index value for element. Elements will be rendered in order of zIndex value from low to high.
#### gridtile #### gridtile

178
THEMES-LEGACY.md
View file

@ -2,7 +2,7 @@
**This document covers the creation of legacy themes only, which is a theme structure that is backward compatible with RetroPie EmulationStation. As ES-DE v2.0 and later has a new theme engine with much improved theming capabilities, this document is mostly intended for historical reference. For creating or porting themes to ES-DE the documentation in [THEMES.md](THEMES.md) should be used instead.** **This document covers the creation of legacy themes only, which is a theme structure that is backward compatible with RetroPie EmulationStation. As ES-DE v2.0 and later has a new theme engine with much improved theming capabilities, this document is mostly intended for historical reference. For creating or porting themes to ES-DE the documentation in [THEMES.md](THEMES.md) should be used instead.**
In general ES-DE is backward compatible with RetroPie theme sets with the notable exception of the _Grid_ view style which is not supported. Themes with grid view styles included will still load correctly, but you can't actually use this view style. As well, any RetroPie theme using the `<resolution>` tag introduced in 2020 will not get loaded. This tag was a very bad idea as it changes sizing of components from relative values to absolute pixel values. In general ES-DE is backward compatible with RetroPie theme sets with the notable exception of the _Grid_ view style which is not supported. Themes with grid view styles included will still load correctly, but you can't actually use this view style. As well, any RetroPie theme using the `<resolution>` tag introduced in 2020 will not get loaded. This tag was a very bad idea as it changes sizing of elements from relative values to absolute pixel values.
Table of contents: Table of contents:
@ -92,7 +92,7 @@ A _view_ can be thought of as a particular "screen" within ES-DE. Views are defi
</view> </view>
``` ```
An *element* is a particular visual element, such as an image or a piece of text. You can modify an element that already exists for a particular view, as was done for the "description" example: An *element* is a particular visual element, such as an image or a piece of text. You can modify an element that already exists for a particular view, as was done for the "description" example:
```xml ```xml
<elementTypeHere name="ExistingElementNameHere"> <elementTypeHere name="ExistingElementNameHere">
@ -112,7 +112,7 @@ Or you can create your own elements by adding `extra="true"`, as was done for th
*Properties* control how a particular *element* looks - for example its position, size, image path etc. The type of the property determines what kinds of values you can use. You can read about the types below in the "Reference" section. Properties are defined like this: *Properties* control how a particular *element* looks - for example its position, size, image path etc. The type of the property determines what kinds of values you can use. You can read about the types below in the "Reference" section. Properties are defined like this:
```xml ```xml
<propertyNameHere>ValueHere</propertyNameHere> <propertyNameHere>ValueHere</propertyNameHere>
@ -121,7 +121,7 @@ Or you can create your own elements by adding `extra="true"`, as was done for th
## Advanced features ## Advanced features
If you are writing a theme it's recommended to launch ES-DE with the `--debug` flag from a terminal window. You can also pass the `--resolution` flag to avoid having the application window fill the entire screen. By doing so, you can read error messages directly in the terminal window without having to open the log file. You can also reload the current gamelist view and system view with `Ctrl-R` if the `--debug` flag has been set. If you are writing a theme it's recommended to launch ES-DE with the `--debug` flag from a terminal window. You can also pass the `--resolution` flag to avoid having the application window fill the entire screen. By doing so, you can read error messages directly in the terminal window without having to open the log file. You can also reload the current gamelist view and system view with `Ctrl-R` if the `--debug` flag has been set.
### The \<include\> tag ### The \<include\> tag
@ -175,7 +175,7 @@ Note that properties can get merged. In the above example the `<color>` tag from
### Theming multiple views simultaneously ### 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 apply the same logo to the basic and detailed views you could write the following: 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 apply the same logo to the basic and detailed views you could write the following:
```xml ```xml
<theme> <theme>
@ -219,7 +219,7 @@ The above is equivalent to:
### Theming multiple elements simultaneously ### Theming multiple elements simultaneously
You can theme multiple elements *of the same type* simultaneously. The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas). This is useful if you want to, say, apply the same color to all the metadata labels: You can theme multiple elements *of the same type* simultaneously. The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas). This is useful if you want to, say, apply the same color to all the metadata labels:
```xml ```xml
<theme> <theme>
@ -370,7 +370,7 @@ Below are the default zIndex values per element type:
### Theme variables ### Theme variables
Theme variables can be used to simplify theme construction. There are 2 types of variables available. Theme variables can be used to simplify theme construction. There are 2 types of variables available.
* System variables * System variables
* Theme defined variables * Theme defined variables
@ -437,11 +437,11 @@ Nesting of variables is supported, so the following could be done:
* `image name="background"` - ALL * `image name="background"` - ALL
- This is a background image that exists for convenience. It goes from (0, 0) to (1, 1). - This is a background image that exists for convenience. It goes from (0, 0) to (1, 1).
* `text name="logoText"` - ALL * `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. - 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 * `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. - 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 * `textlist name="gamelist"` - ALL
- The gamelist. `primaryColor` is for games, `secondaryColor` is for folders. Centered by default. - The gamelist. `primaryColor` is for games, `secondaryColor` is for folders. Centered by default.
#### detailed #### detailed
@ -450,11 +450,11 @@ Nesting of variables is supported, so the following could be done:
* `image name="background"` - ALL * `image name="background"` - ALL
- This is a background image that exists for convenience. It goes from (0, 0) to (1, 1). - This is a background image that exists for convenience. It goes from (0, 0) to (1, 1).
* `text name="logoText"` - ALL * `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. - 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 * `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. - 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 * `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.
* `text name="gamelistInfo"` - ALL * `text name="gamelistInfo"` - ALL
- Displays the game count (all games as well as favorites), any applied filters, and a folder icon if a folder has been entered. If this text is left aligned, the folder icon will be placed to the right of the other information, and if it's right aligned, the folder icon will be placed to the left. Left aligned by default. - Displays the game count (all games as well as favorites), any applied filters, and a folder icon if a folder has been entered. If this text is left aligned, the folder icon will be placed to the right of the other information, and if it's right aligned, the folder icon will be placed to the left. Left aligned by default.
@ -488,11 +488,11 @@ Nesting of variables is supported, so the following could be done:
* `badges name="md_badges"` - ALL * `badges name="md_badges"` - ALL
- The "badges" metadata. Displayed as a group of badges that indicate metadata such as favorites and completed games. - The "badges" metadata. Displayed as a group of badges that indicate metadata such as favorites and completed games.
* `datetime name="md_lastplayed"` - ALL * `datetime name="md_lastplayed"` - ALL
- The "lastplayed" metadata. Displayed as a string representing the time relative to "now" (e.g. "3 hours ago"). - The "lastplayed" metadata. Displayed as a string representing the time relative to "now" (e.g. "3 hours ago").
* `text name="md_playcount"` - ALL * `text name="md_playcount"` - ALL
- The "playcount" metadata (number of times the game has been played). - The "playcount" metadata (number of times the game has been played).
* `text name="md_description"` - POSITION | SIZE | FONT_PATH | FONT_SIZE | COLOR | Z_INDEX * `text name="md_description"` - POSITION | SIZE | FONT_PATH | FONT_SIZE | COLOR | Z_INDEX
- Text is the "desc" metadata. If no `pos`/`size` is specified, will move and resize to fit under the lowest label and reach to the bottom of the screen. - Text is the "desc" metadata. If no `pos`/`size` is specified, will move and resize to fit under the lowest label and reach to the bottom of the screen.
* `text name="md_name"` - ALL * `text name="md_name"` - ALL
- The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default - The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default
@ -503,11 +503,11 @@ Nesting of variables is supported, so the following could be done:
* `image name="background"` - ALL * `image name="background"` - ALL
- This is a background image that exists for convenience. It goes from (0, 0) to (1, 1). - This is a background image that exists for convenience. It goes from (0, 0) to (1, 1).
* `text name="logoText"` - ALL * `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. - 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 * `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. - 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 * `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.
* `text name="gamelistInfo"` - ALL * `text name="gamelistInfo"` - ALL
- Displays the game count (all games as well as favorites), any applied filters, and a folder icon if a folder has been entered. If this text is left aligned, the folder icon will be placed to the right of the other information, and if it's right aligned, the folder icon will be placed to the left. Left aligned by default. - Displays the game count (all games as well as favorites), any applied filters, and a folder icon if a folder has been entered. If this text is left aligned, the folder icon will be placed to the right of the other information, and if it's right aligned, the folder icon will be placed to the left. Left aligned by default.
@ -545,28 +545,28 @@ Nesting of variables is supported, so the following could be done:
* `badges name="md_badges"` - ALL * `badges name="md_badges"` - ALL
- The "badges" metadata. Displayed as a group of badges that indicate metadata such as favorites and completed games. - The "badges" metadata. Displayed as a group of badges that indicate metadata such as favorites and completed games.
* `datetime name="md_lastplayed"` - ALL * `datetime name="md_lastplayed"` - ALL
- The "lastplayed" metadata. Displayed as a string representing the time relative to "now" (e.g. "3 hours ago"). - The "lastplayed" metadata. Displayed as a string representing the time relative to "now" (e.g. "3 hours ago").
* `text name="md_playcount"` - ALL * `text name="md_playcount"` - ALL
- The "playcount" metadata (number of times the game has been played). - The "playcount" metadata (number of times the game has been played).
* `text name="md_description"` - POSITION | SIZE | FONT_PATH | FONT_SIZE | COLOR | Z_INDEX * `text name="md_description"` - POSITION | SIZE | FONT_PATH | FONT_SIZE | COLOR | Z_INDEX
- Text is the "desc" metadata. If no `pos`/`size` is specified, will move and resize to fit under the lowest label and reach to the bottom of the screen. - Text is the "desc" metadata. If no `pos`/`size` is specified, will move and resize to fit under the lowest label and reach to the bottom of the screen.
* `text name="md_name"` - ALL * `text name="md_name"` - ALL
- The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default - The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default
### Types of properties ### 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_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. * 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.
* 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) unless overridden using the --home command line option. 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`. * 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) unless overridden using the --home command line option. 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`. * 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). * COLOR - a hexadecimal RGB or RGBA color (6 or 8 digits). If 6 digits, will assume the alpha channel is `FF` (not transparent).
* FLOAT - a decimal. * FLOAT - a decimal.
* STRING - a string of text. * STRING - a string of text.
### Types of elements and their properties ### Types of elements and their properties
Common to almost all elements is a `pos` and `size` property of the NORMALIZED_PAIR type. They are normalized in terms of their "parent" object's size; 99% of the time, this is just the size of the screen. In this case, `<pos>0 0</pos>` would correspond to the top left corner, and `<pos>1 1</pos>` the bottom right corner (a positive Y value points further down). `pos` almost always refers to the top left corner of your element. You *can* use numbers outside of the [0..1] range if you want to place an element partially or completely off-screen. Common to almost all elements is a `pos` and `size` property of the NORMALIZED_PAIR type. They are normalized in terms of their "parent" object's size; 99% of the time, this is just the size of the screen. In this case, `<pos>0 0</pos>` would correspond to the top left corner, and `<pos>1 1</pos>` the bottom right corner (a positive Y value points further down). `pos` almost always refers to the top left corner of your element. You *can* use numbers outside of the [0..1] range if you want to place an element partially or completely off-screen.
The order you define properties in does not matter. The order you define properties in does not matter.
Remember, you do *not* need to specify every property! Remember, you do *not* need to specify every property!
@ -580,25 +580,25 @@ Can be created as an extra.
* `size` - 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 image's aspect ratio. - If only one axis is specified (and the other is zero), the other will be automatically calculated in accordance with the image's aspect ratio.
* `maxSize` - type: NORMALIZED_PAIR. * `maxSize` - type: NORMALIZED_PAIR.
- The image will be resized as large as possible so that it fits within this size and maintains 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). - The image will be resized as large as possible so that it fits within this size and maintains 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).
* `origin` - type: NORMALIZED_PAIR. * `origin` - type: NORMALIZED_PAIR.
- Where on the image `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the image exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. - Where on the image `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the image exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied.
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the image will be rotated. Default is `0.5 0.5`. - Point around which the image will be rotated. Default is `0.5 0.5`.
* `path` - type: PATH. * `path` - type: PATH.
- Path to the image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif). - Path to the image file. Most common extensions are supported (including .jpg, .png, and unanimated .gif).
* `default` - type: PATH. * `default` - type: PATH.
- Path to default image file. Default image will be displayed when selected game does not have an image. - Path to default image file. Default image will be displayed when selected game does not have an image.
* `tile` - type: BOOLEAN. * `tile` - type: BOOLEAN.
- If true, the image will be tiled instead of stretched to fit its size. Useful for backgrounds. - If true, the image will be tiled instead of stretched to fit its size. Useful for backgrounds.
* `color` - type: COLOR. * `color` - type: COLOR.
- Multiply each pixel's color by this color. For example, an all-white image with `<color>FF0000</color>` would become completely red. You can also control the transparency of an image with `<color>FFFFFFAA</color>` - keeping all the pixels their normal color and only affecting the alpha channel. - Multiply each pixel's color by this color. For example, an all-white image with `<color>FF0000</color>` would become completely red. You can also control the transparency of an image with `<color>FFFFFFAA</color>` - keeping all the pixels their normal color and only affecting the alpha channel.
* `visible` - type: BOOLEAN. * `visible` - type: BOOLEAN.
- If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. - If true, element will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view.
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high. - z-index value for element. Elements will be rendered in order of z-index value from low to high.
#### video #### video
@ -606,25 +606,25 @@ Can be created as an extra.
* `size` - 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. - 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.
* `maxSize` - type: NORMALIZED_PAIR. * `maxSize` - type: NORMALIZED_PAIR.
- The video will be resized as large as possible so that it fits within this size and maintains its aspect ratio. Use this instead of `size` when you don't know what kind of video you're using so it doesn't get grossly oversized on one axis (e.g. with a game's video metadata). - The video will be resized as large as possible so that it fits within this size and maintains its aspect ratio. Use this instead of `size` when you don't know what kind of video you're using so it doesn't get grossly oversized on one axis (e.g. with a game's video metadata).
* `origin` - type: NORMALIZED_PAIR. * `origin` - type: NORMALIZED_PAIR.
- Where on the image `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the image exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. - Where on the image `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the image exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied.
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the text will be rotated. Default is `0.5 0.5`. - Point around which the text will be rotated. Default is `0.5 0.5`.
* `delay` - type: FLOAT. Default is false. * `delay` - type: FLOAT. Default is false.
- Delay in seconds before video will start playing. - Delay in seconds before video will start playing.
* `default` - type: PATH. * `default` - type: PATH.
- Path to default video file. Default video will be played when selected game does not have a video. - Path to default video file. Default video will be played when selected game does not have a video.
* `showSnapshotNoVideo` - type: BOOLEAN * `showSnapshotNoVideo` - type: BOOLEAN
- If true, image will be shown when selected game does not have a video and no `default` video is configured. - If true, image will be shown when selected game does not have a video and no `default` video is configured.
* `showSnapshotDelay` - type: BOOLEAN * `showSnapshotDelay` - type: BOOLEAN
- If true, playing of video will be delayed for `delayed` seconds, when game is selected. - If true, playing of video will be delayed for `delayed` seconds, when game is selected.
* `visible` - type: BOOLEAN. * `visible` - type: BOOLEAN.
- If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. - If true, element will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view.
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high. - z-index value for element. Elements will be rendered in order of z-index value from low to high.
#### text #### text
@ -635,11 +635,11 @@ Can be created as an extra.
- Possible combinations: - Possible combinations:
- `0 0` - automatically size so text fits on one line (expanding horizontally). - `0 0` - automatically size so text fits on one line (expanding horizontally).
- `w 0` - automatically wrap text so it doesn't go beyond `w` (expanding vertically). - `w 0` - automatically wrap text so it doesn't go beyond `w` (expanding vertically).
- `w h` - works like a "text box." If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...). - `w h` - works like a "text box". If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...).
* `origin` - type: NORMALIZED_PAIR. * `origin` - type: NORMALIZED_PAIR.
- Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the component exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied.
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the text will be rotated. Default is `0.5 0.5`. - Point around which the text will be rotated. Default is `0.5 0.5`.
* `text` - type: STRING. * `text` - type: STRING.
@ -650,20 +650,20 @@ Can be created as an extra.
* `fontSize` - type: FLOAT. * `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). - 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).
* `alignment` - type: STRING. * `alignment` - type: STRING.
- Valid values are "left", "center", or "right". Controls alignment on the X axis. "center" will also align vertically. - Valid values are "left", "center", or "right". Controls alignment on the X axis. "center" will also align vertically.
* `forceUppercase` - type: BOOLEAN. Draw text in uppercase. * `forceUppercase` - type: BOOLEAN. Draw text in uppercase.
* `lineSpacing` - type: FLOAT. Controls the space between lines (as a multiple of font height). Default is 1.5. * `lineSpacing` - type: FLOAT. Controls the space between lines (as a multiple of font height). Default is 1.5.
* `visible` - type: BOOLEAN. * `visible` - type: BOOLEAN.
- If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. - If true, element will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view.
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high. - z-index value for element. Elements will be rendered in order of z-index value from low to high.
#### textlist #### textlist
* `pos` - type: NORMALIZED_PAIR. * `pos` - type: NORMALIZED_PAIR.
* `size` - type: NORMALIZED_PAIR. * `size` - type: NORMALIZED_PAIR.
* `origin` - type: NORMALIZED_PAIR. * `origin` - type: NORMALIZED_PAIR.
- Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the component exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied.
* `selectorColor` - type: COLOR. * `selectorColor` - type: COLOR.
- Color of the "selector bar." - Color of the "selector bar."
* `selectorImagePath` - type: PATH. * `selectorImagePath` - type: PATH.
@ -673,23 +673,23 @@ Can be created as an extra.
* `selectorHeight` - type: FLOAT. * `selectorHeight` - type: FLOAT.
- Height of the "selector bar". - Height of the "selector bar".
* `selectorOffsetY` - type: FLOAT. * `selectorOffsetY` - type: FLOAT.
- Allows moving of the "selector bar" up or down from its computed position. Useful for fine tuning the position of the "selector bar" relative to the text. - Allows moving of the "selector bar" up or down from its computed position. Useful for fine tuning the position of the "selector bar" relative to the text.
* `selectedColor` - type: COLOR. * `selectedColor` - type: COLOR.
- Color of the highlighted entry text. - Color of the highlighted entry text.
* `primaryColor` - type: COLOR. * `primaryColor` - type: COLOR.
- Primary color; what this means depends on the text list. For example, for game lists, it is the color of a game. - Primary color; what this means depends on the text list. For example, for game lists, it is the color of a game.
* `secondaryColor` - type: COLOR. * `secondaryColor` - type: COLOR.
- Secondary color; what this means depends on the text list. For example, for game lists, it is the color of a folder. - Secondary color; what this means depends on the text list. For example, for game lists, it is the color of a folder.
* `fontPath` - type: PATH. * `fontPath` - type: PATH.
* `fontSize` - type: FLOAT. * `fontSize` - type: FLOAT.
* `alignment` - type: STRING. * `alignment` - type: STRING.
- Valid values are "left", "center", or "right". Controls alignment on the X axis. - Valid values are "left", "center", or "right". Controls alignment on the X axis.
* `horizontalMargin` - type: FLOAT. * `horizontalMargin` - type: FLOAT.
- Horizontal offset for text from the alignment point. If `alignment` is "left", offsets the text to the right. If `alignment` is "right", offsets text to the left. No effect if `alignment` is "center". Given as a percentage of the element's parent's width (same unit as `size`'s X value). - Horizontal offset for text from the alignment point. If `alignment` is "left", offsets the text to the right. If `alignment` is "right", offsets text to the left. No effect if `alignment` is "center". Given as a percentage of the element's parent's width (same unit as `size`'s X value).
* `forceUppercase` - type: BOOLEAN. Draw text in uppercase. * `forceUppercase` - type: BOOLEAN. Draw text in uppercase.
* `lineSpacing` - type: FLOAT. Controls the space between lines (as a multiple of font height). Default is 1.5. * `lineSpacing` - type: FLOAT. Controls the space between lines (as a multiple of font height). Default is 1.5.
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high. - z-index value for element. Elements will be rendered in order of z-index value from low to high.
#### ninepatch #### ninepatch
@ -697,9 +697,9 @@ Can be created as an extra.
* `size` - type: NORMALIZED_PAIR. * `size` - type: NORMALIZED_PAIR.
* `path` - type: PATH. * `path` - type: PATH.
* `visible` - type: BOOLEAN. * `visible` - type: BOOLEAN.
- If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. - If true, element will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view.
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high. - z-index value for element. Elements will be rendered in order of z-index value from low to high.
ES-DE 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). ES-DE 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).
@ -707,23 +707,23 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren
* `pos` - type: NORMALIZED_PAIR. * `pos` - type: NORMALIZED_PAIR.
* `size` - 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.) - 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.)
* `origin` - type: NORMALIZED_PAIR. * `origin` - type: NORMALIZED_PAIR.
- Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the component exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied.
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the rating should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - angle in degrees that the rating should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the rating will be rotated. Default is `0.5 0.5`. - Point around which the rating will be rotated. Default is `0.5 0.5`.
* `filledPath` - type: PATH. * `filledPath` - type: PATH.
- Path to the "filled star" image. Image must be square (width equals height). - Path to the "filled star" image. Image must be square (width equals height).
* `unfilledPath` - type: PATH. * `unfilledPath` - type: PATH.
- Path to the "unfilled star" image. Image must be square (width equals height). - Path to the "unfilled star" image. Image must be square (width equals height).
* `color` - type: COLOR. * `color` - type: COLOR.
- Multiply each pixel's color by this color. For example, an all-white image with `<color>FF0000</color>` would become completely red. You can also control the transparency of an image with `<color>FFFFFFAA</color>` - keeping all the pixels their normal color and only affecting the alpha channel. - Multiply each pixel's color by this color. For example, an all-white image with `<color>FF0000</color>` would become completely red. You can also control the transparency of an image with `<color>FFFFFFAA</color>` - keeping all the pixels their normal color and only affecting the alpha channel.
* `visible` - type: BOOLEAN. * `visible` - type: BOOLEAN.
- If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. - If true, element will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view.
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high. - z-index value for element. Elements will be rendered in order of z-index value from low to high.
#### datetime #### datetime
* `pos` - type: NORMALIZED_PAIR. * `pos` - type: NORMALIZED_PAIR.
@ -731,11 +731,11 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren
- Possible combinations: - Possible combinations:
- `0 0` - automatically size so text fits on one line (expanding horizontally). - `0 0` - automatically size so text fits on one line (expanding horizontally).
- `w 0` - automatically wrap text so it doesn't go beyond `w` (expanding vertically). - `w 0` - automatically wrap text so it doesn't go beyond `w` (expanding vertically).
- `w h` - works like a "text box." If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...). - `w h` - works like a "text box". If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...).
* `origin` - type: NORMALIZED_PAIR. * `origin` - type: NORMALIZED_PAIR.
- Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the component exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied.
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. - angle in degrees that the text should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the text will be rotated. Default is `0.5 0.5`. - Point around which the text will be rotated. Default is `0.5 0.5`.
* `color` - type: COLOR. * `color` - type: COLOR.
@ -745,14 +745,14 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren
* `fontSize` - type: FLOAT. * `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). - 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).
* `alignment` - type: STRING. * `alignment` - type: STRING.
- Valid values are "left", "center", or "right". Controls alignment on the X axis. "center" will also align vertically. - Valid values are "left", "center", or "right". Controls alignment on the X axis. "center" will also align vertically.
* `forceUppercase` - type: BOOLEAN. Draw text in uppercase. * `forceUppercase` - type: BOOLEAN. Draw text in uppercase.
* `lineSpacing` - type: FLOAT. Controls the space between lines (as a multiple of font height). Default is 1.5. * `lineSpacing` - type: FLOAT. Controls the space between lines (as a multiple of font height). Default is 1.5.
* `visible` - type: BOOLEAN. * `visible` - type: BOOLEAN.
- If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. - If true, element will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view.
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high. - z-index value for element. Elements will be rendered in order of z-index value from low to high.
* `displayRelative` - type: BOOLEAN. Renders the datetime as a a relative string (ex: 'x days ago') * `displayRelative` - type: BOOLEAN. Renders the datetime as a a relative string (ex: 'x days ago')
* `format` - type: STRING. Specifies format for rendering datetime. * `format` - type: STRING. Specifies format for rendering datetime.
- %Y: The year, including the century (1900) - %Y: The year, including the century (1900)
- %m: The month number [01,12] - %m: The month number [01,12]
@ -765,8 +765,8 @@ ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Curren
* `pos` - type: NORMALIZED_PAIR. Default is "0.012 0.9515" * `pos` - type: NORMALIZED_PAIR. Default is "0.012 0.9515"
* `origin` - type: NORMALIZED_PAIR. * `origin` - type: NORMALIZED_PAIR.
- Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place
the component exactly in the middle of the screen. the element exactly in the middle of the screen.
* `textColor` - type: COLOR. Default is 777777FF. * `textColor` - type: COLOR. Default is 777777FF.
* `textColorDimmed` - type: COLOR. Default is the same value as textColor. Must be placed under the 'system' view. * `textColorDimmed` - type: COLOR. Default is the same value as textColor. Must be placed under the 'system' view.
* `iconColor` - type: COLOR. Default is 777777FF. * `iconColor` - type: COLOR. Default is 777777FF.
@ -816,9 +816,9 @@ It's strongly recommended to use the same image dimensions for all badges as var
- Possible combinations: - Possible combinations:
- `w h` - Dimensions of the badges container. The badges will be scaled to fit within these dimensions. Minimum value per axis is `0.03`, maximum value is `1.0`. Default is `0.15 0.20`. - `w h` - Dimensions of the badges container. The badges will be scaled to fit within these dimensions. Minimum value per axis is `0.03`, maximum value is `1.0`. Default is `0.15 0.20`.
* `origin` - type: NORMALIZED_PAIR. * `origin` - type: NORMALIZED_PAIR.
- Where on the component `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the component exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. Default is `0.5 0.5`. - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. Default is `0.5 0.5`.
* `rotation` - type: FLOAT. * `rotation` - type: FLOAT.
- angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. Default is `0`. - angle in degrees that the image should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. Default is `0`.
* `rotationOrigin` - type: NORMALIZED_PAIR. * `rotationOrigin` - type: NORMALIZED_PAIR.
- Point around which the image will be rotated. Default is `0.5 0.5`. - Point around which the image will be rotated. Default is `0.5 0.5`.
* `alignment` - type: STRING. * `alignment` - type: STRING.
@ -850,9 +850,9 @@ It's strongly recommended to use the same image dimensions for all badges as var
- A controller icon override. Specify the controller type in the attribute `controller`. These are the available types: - A controller icon override. Specify the controller type in the attribute `controller`. These are the available types:
- `gamepad_generic`, `gamepad_nintendo_nes`, `gamepad_nintendo_snes`, `gamepad_nintendo_64`, `gamepad_playstation`, `gamepad_sega_md_3_buttons`, `gamepad_sega_md_6_buttons`, `gamepad_xbox`, `joystick_generic`, `joystick_arcade_no_buttons`, `joystick_arcade_1_button`, `joystick_arcade_2_buttons`, `joystick_arcade_3_buttons`, `joystick_arcade_4_buttons`, `joystick_arcade_5_buttons`, `joystick_arcade_6_buttons`, `keyboard_generic`, `keyboard_and_mouse_generic`, `mouse_generic`, `mouse_amiga`, `lightgun_generic`, `lightgun_nintendo`, `steering_wheel_generic`, `flight_stick_generic`, `spinner_generic`, `trackball_generic`, `wii_remote_nintendo`, `wii_remote_and_nunchuk_nintendo`, `joycon_left_or_right_nintendo`, `joycon_pair_nintendo`, `unknown`. - `gamepad_generic`, `gamepad_nintendo_nes`, `gamepad_nintendo_snes`, `gamepad_nintendo_64`, `gamepad_playstation`, `gamepad_sega_md_3_buttons`, `gamepad_sega_md_6_buttons`, `gamepad_xbox`, `joystick_generic`, `joystick_arcade_no_buttons`, `joystick_arcade_1_button`, `joystick_arcade_2_buttons`, `joystick_arcade_3_buttons`, `joystick_arcade_4_buttons`, `joystick_arcade_5_buttons`, `joystick_arcade_6_buttons`, `keyboard_generic`, `keyboard_and_mouse_generic`, `mouse_generic`, `mouse_amiga`, `lightgun_generic`, `lightgun_nintendo`, `steering_wheel_generic`, `flight_stick_generic`, `spinner_generic`, `trackball_generic`, `wii_remote_nintendo`, `wii_remote_and_nunchuk_nintendo`, `joycon_left_or_right_nintendo`, `joycon_pair_nintendo`, `unknown`.
* `visible` - type: BOOLEAN. * `visible` - type: BOOLEAN.
- If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. - If true, element will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view.
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high. Default is `50`. - z-index value for element. Elements will be rendered in order of z-index value from low to high. Default is `50`.
#### carousel #### carousel
@ -861,18 +861,18 @@ It's strongly recommended to use the same image dimensions for all badges as var
- Accepted values are "horizontal", "vertical", "horizontal_wheel" or "vertical_wheel". - Accepted values are "horizontal", "vertical", "horizontal_wheel" or "vertical_wheel".
- Default is "horizontal". - Default is "horizontal".
* `size` - type: NORMALIZED_PAIR. Default is "1 0.2325" * `size` - type: NORMALIZED_PAIR. Default is "1 0.2325"
* `pos` - type: NORMALIZED_PAIR. Default is "0 0.38375". * `pos` - type: NORMALIZED_PAIR. Default is "0 0.38375".
* `origin` - type: NORMALIZED_PAIR. * `origin` - type: NORMALIZED_PAIR.
- Where on the carousel `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the carousel exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. - Where on the carousel `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the carousel exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied.
* `color` - type: COLOR. * `color` - type: COLOR.
- Controls the color of the carousel background. - Controls the color of the carousel background.
- Default is FFFFFFD8 - Default is FFFFFFD8
* `logoSize` - type: NORMALIZED_PAIR. Default is "0.25 0.155" * `logoSize` - type: NORMALIZED_PAIR. Default is "0.25 0.155"
* `logoScale` - type: FLOAT. * `logoScale` - type: FLOAT.
- Selected logo is increased in size by this scale - Selected logo is increased in size by this scale
- Default is 1.2 - Default is 1.2
* `logoRotation` - type: FLOAT. * `logoRotation` - type: FLOAT.
- Angle in degrees that the logos should be rotated. Value should be positive. - Angle in degrees that the logos should be rotated. Value should be positive.
- Default is 7.5 - Default is 7.5
- This property only applies when `type` is "horizontal_wheel" or "vertical_wheel". - This property only applies when `type` is "horizontal_wheel" or "vertical_wheel".
* `logoRotationOrigin` - type: NORMALIZED_PAIR. * `logoRotationOrigin` - type: NORMALIZED_PAIR.
@ -887,9 +887,9 @@ It's strongly recommended to use the same image dimensions for all badges as var
- Sets the number of logos to display in the carousel. Note that fractional values are rounded up. - Sets the number of logos to display in the carousel. Note that fractional values are rounded up.
- Default is 3 - Default is 3
* `zIndex` - type: FLOAT. * `zIndex` - type: FLOAT.
- z-index value for component. Components will be rendered in order of z-index value from low to high with the carousel above all other components. - z-index value for element. Elements will be rendered in order of z-index value from low to high with the carousel above all other elements.
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. 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.
## Example theme sets ## Example theme sets

10
USERGUIDE-DEV.md
View file

@ -1764,6 +1764,10 @@ This entry is only visible if the system is a custom collection and it's current
This opens the metadata editor for the currently selected game file or folder. This opens the metadata editor for the currently selected game file or folder.
### Enter folder (override folder link)
If the current game is a folder which has a _folder link_ configured (meaning it points to a file inside the folder structure that will be launched when pressing the _A_ button), then this entry will appear in the menu. It simply overrides the link and enters the folder just as if no link would have been configured. The folder link functionality is described in more detail below.
## Metadata editor ## Metadata editor
In the metadata editor, you can modify the metadata, scrape for game info and media files, clear the entry which will delete all metadata and game media files, or delete the entire game which also removes its file on the filesystem. When manually modifying a value, it will change color from gray to blue, and if the scraper has changed a value, it will change to red. When leaving the metadata editor you will be asked whether you want to save any settings done manually or by the scraper. In the metadata editor, you can modify the metadata, scrape for game info and media files, clear the entry which will delete all metadata and game media files, or delete the entire game which also removes its file on the filesystem. When manually modifying a value, it will change color from gray to blue, and if the scraper has changed a value, it will change to red. When leaving the metadata editor you will be asked whether you want to save any settings done manually or by the scraper.
@ -1859,6 +1863,10 @@ This entry provides a selection of controller icons that are built into ES-DE (a
If the option _Enable alternative emulators per game_ has been enabled, there will be an entry shown where you can select between alternative emulators for the specific game. There is a similar _Alternative emulators_ entry under the _Other settings_ menu, but that will apply the selection to the entire game system. If you select an alternative for a specific game using the metadata editor, that will take precedence and override any system-wide emulator selection (the currently selected system-wide emulator will be clearly marked on the selection screen). The alternative emulators need to be defined in the es_systems.xml file, and if there are no alternatives available for the current system, this row in the metadata editor will be grayed out. If you select an alternative emulator and later remove its corresponding entry from the es_systems.xml file, an error notice will be shown on this row. In this case you have the option to remove the invalid entry. But even if there is an invalid entry, games will still launch using the default emulator while logging a warning message to the es_log.txt file. Apart from this, the emulator selection should hopefully be self-explanatory. If the option _Enable alternative emulators per game_ has been enabled, there will be an entry shown where you can select between alternative emulators for the specific game. There is a similar _Alternative emulators_ entry under the _Other settings_ menu, but that will apply the selection to the entire game system. If you select an alternative for a specific game using the metadata editor, that will take precedence and override any system-wide emulator selection (the currently selected system-wide emulator will be clearly marked on the selection screen). The alternative emulators need to be defined in the es_systems.xml file, and if there are no alternatives available for the current system, this row in the metadata editor will be grayed out. If you select an alternative emulator and later remove its corresponding entry from the es_systems.xml file, an error notice will be shown on this row. In this case you have the option to remove the invalid entry. But even if there is an invalid entry, games will still launch using the default emulator while logging a warning message to the es_log.txt file. Apart from this, the emulator selection should hopefully be self-explanatory.
**Folder link** _(folders only)_
Using this option it's possible to link a specific file inside the game's folder structure that will be launched directly instead of entering the folder when pressing the _A_ button. This is very useful for systems where there are multiple files per game, such as multi-disc games where an .m3u file is used to launch the game. As the name implies this is only a link, and as folders can't be part of collections (the automatic collections _All games, Favorites_ and _Last played_ as well as any custom collections) it's the linked file inside the folder that is included in such collections. So for instance, launching a game via a linked folder will have the linked file show up in the _Last played_ collection rather than the folder itself. This also means that you should scrape the linked file in addition to the folder to be able to see game media and metadata throughout the application. To override the folder link and enter the directory, there is an entry available in the game options menu.
### Buttons ### Buttons
For game files, there will be five buttons displayed on the bottom of the metadata editor window, and for folders there will be four. These are their functions: For game files, there will be five buttons displayed on the bottom of the metadata editor window, and for folders there will be four. These are their functions:
@ -1944,6 +1952,8 @@ Only files can be part of collections, not folders. Games marked as hidden or to
During the time that the collection is being edited, any game that is part of the collection is marked with a leading tick symbol in the game name. During the time that the collection is being edited, any game that is part of the collection is marked with a leading tick symbol in the game name.
As well, when editing custom collections the _folder link_ configuration is disabled, making it possible to enter folders with such configuration just as if there were no folder links configured.
When you are done adding games, you can either open the main menu and go to **Game collection settings** and select the **Finish editing 'Platform' collection** or you can open the game options menu and select the same option there. The latter works from within any gamelist, so you don't need to first navigate back to the collection that you're editing. When you are done adding games, you can either open the main menu and go to **Game collection settings** and select the **Finish editing 'Platform' collection** or you can open the game options menu and select the same option there. The latter works from within any gamelist, so you don't need to first navigate back to the collection that you're editing.
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**. 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**.