mirror of
https://github.com/RetroDECK/ES-DE.git
synced 2024-11-22 06:05:38 +00:00
Rewrote the theming documentation.
This commit is contained in:
Aloshi
parent
8d1ac3087e
commit
5a84bc03ea
399
THEMES.md
399
THEMES.md
|
|
@ -1,156 +1,277 @@
|
||||||
Themes
|
Themes
|
||||||
======
|
======
|
||||||
|
|
||||||
EmulationStation allows each system to have its own "theme." A theme is a collection of resources defined in an XML document.
|
EmulationStation allows each system to have its own "theme." A theme is a collection **views** that define some **elements**, each with their own **properties**.
|
||||||
|
|
||||||
Themes are loaded like this:
|
|
||||||
|
|
||||||
1. Initialize to default values.
|
Simple Example
|
||||||
2. If `$HOME/.emulationstation/es_theme_default.xml` exists, load it.
|
==============
|
||||||
3. If there is a `theme.xml` present in the root of a system's `path` directory, load it.
|
|
||||||
|
|
||||||
IF NOT, If `$HOME/.emulationstation/%SYSTEMNAME%/theme.xml` exists, load it.
|
Here is a very simple theme that changes the description text's color:
|
||||||
|
|
||||||
Example
|
|
||||||
=======
|
|
||||||
|
|
||||||
```
|
```
|
||||||
<theme>
|
<theme>
|
||||||
<listPrimaryColor>0000FF</listPrimaryColor>
|
<version>3</version>
|
||||||
<listSecondaryColor>00FF00</listSecondaryColor>
|
<view name="detailed">
|
||||||
|
<text name="description">
|
||||||
<listFont>
|
<color>00FF00</color>
|
||||||
<path>./../all_themes/font.ttf</path>
|
</text>
|
||||||
<size>0.045</size>
|
<image name="my_image" extra="true">
|
||||||
</listFont>
|
<pos>0.5 0.5</pos>
|
||||||
|
<origin>0.5 0.5</origin>
|
||||||
<descriptionFont>
|
<size>0.8 0.8</size>
|
||||||
<path>./../all_themes/font.ttf</path>
|
<path>./my_art/my_awesome_image.jpg</path>
|
||||||
<size>0.035</size>
|
</image>
|
||||||
</descriptionFont>
|
</view>
|
||||||
|
|
||||||
<backgroundImage>
|
|
||||||
<path>./theme/background.png</path>
|
|
||||||
<tile>true</tile>
|
|
||||||
</backgroundImage>
|
|
||||||
|
|
||||||
<headerImage>
|
|
||||||
<path>./theme/logo.png</path>
|
|
||||||
<tile>false</tile>
|
|
||||||
</headerImage>
|
|
||||||
|
|
||||||
<scrollSound>./../all_themes/scrollSound.wav</scrollSound>
|
|
||||||
</theme>
|
</theme>
|
||||||
```
|
```
|
||||||
|
|
||||||
Themes must be enclosed in a `<theme>` tag.
|
How it works
|
||||||
|
|
||||||
All paths automatically expand `./` to the folder containing the theme.xml.
|
|
||||||
|
|
||||||
All paths automatically expand `~/` to the home directory ($HOME on Linux, %HOMEPATH% on Windows).
|
|
||||||
|
|
||||||
Stuff you can define
|
|
||||||
====================
|
|
||||||
|
|
||||||
Fonts
|
|
||||||
=====
|
|
||||||
|
|
||||||
Fonts are defined like so:
|
|
||||||
```
|
|
||||||
<resourceName>
|
|
||||||
<!-- Path is optional. -->
|
|
||||||
<path>./some/path/here.ttf</path>
|
|
||||||
<!-- Size is a percentage of screen height. Optional. -->
|
|
||||||
<size>0.035</size>
|
|
||||||
</resourceName>
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
`<listFont>` - Default size: 0.045.
|
|
||||||
|
|
||||||
`<descriptionFont>` - Default size: 0.035.
|
|
||||||
|
|
||||||
`<fastSelectLetterFont>` - Default size: 0.15.
|
|
||||||
|
|
||||||
Colors
|
|
||||||
======
|
|
||||||
|
|
||||||
Colors are defined in hex, like this:
|
|
||||||
|
|
||||||
`<resourceName>00FF00FF</resourceName>`
|
|
||||||
|
|
||||||
or
|
|
||||||
|
|
||||||
`<resourceName>00FF00</resourceName>`
|
|
||||||
|
|
||||||
(without the alpha channel specified - will assume FF)
|
|
||||||
|
|
||||||
|
|
||||||
`<listPrimaryColor>` - Default: 0000FFFF.
|
|
||||||
|
|
||||||
`<listSecondaryColor>` - Default: 00FF00FF.
|
|
||||||
|
|
||||||
`<listSelectorColor>` - Default: 000000FF.
|
|
||||||
|
|
||||||
`<listSelectedColor>` - Default: 00000000.
|
|
||||||
|
|
||||||
`<descriptionColor>` - Default: 48474DFF.
|
|
||||||
|
|
||||||
`<fastSelectLetterColor>` - Default: FFFFFFFF.
|
|
||||||
|
|
||||||
`<fastSelectTextColor>` - Default: DDDDDDFF.
|
|
||||||
|
|
||||||
Images
|
|
||||||
======
|
|
||||||
|
|
||||||
Images are defined like this:
|
|
||||||
```
|
|
||||||
<resourceName>
|
|
||||||
<path>./some/path/here.png</path>
|
|
||||||
<!-- Can be true or false. -->
|
|
||||||
<tile>true</tile>
|
|
||||||
</resourceName>
|
|
||||||
```
|
|
||||||
Pretty much any image format is supported.
|
|
||||||
|
|
||||||
|
|
||||||
`<backgroundImage>` - No default.
|
|
||||||
|
|
||||||
`<headerImage>` - No default.
|
|
||||||
|
|
||||||
`<infoBackgroundImage>` - No default.
|
|
||||||
|
|
||||||
`<verticalDividerImage>` - No default.
|
|
||||||
|
|
||||||
`<systemImage>` - No default. Large image, shown in the system select menu.
|
|
||||||
|
|
||||||
`<fastSelectBackgroundImage>` - Nine patch. Default is the "button.png" resource.
|
|
||||||
|
|
||||||
Sounds
|
|
||||||
======
|
|
||||||
|
|
||||||
Sounds are defined like this:
|
|
||||||
|
|
||||||
`<resourceName>./some/path/here.wav</resourceName>`
|
|
||||||
|
|
||||||
Only .wav files are supported.
|
|
||||||
|
|
||||||
|
|
||||||
`<scrollSound>` - No default. Played when a list scrolls.
|
|
||||||
|
|
||||||
`<gameSelectSound>` - No default. Played when a game is launched.
|
|
||||||
|
|
||||||
`<backSound>` - No default. Played when leaving a folder in the game list.
|
|
||||||
|
|
||||||
`<menuOpenSound>` - No default. Played when the menu is opened.
|
|
||||||
|
|
||||||
`<menuCloseSound>` - No default. Played when the menu is closed.
|
|
||||||
|
|
||||||
|
|
||||||
Nine Patches
|
|
||||||
============
|
============
|
||||||
|
|
||||||
EmulationStation borrows the concept of "nine patches" from Android (or "9-Slices"). Currently the implementation is very simple and hard-coded to only use 48x48px images (16x16px for each "patch"). Check the `data/resources` directory for some examples (button.png, frame.png).
|
Everything must be inside a `<theme>` tag.
|
||||||
|
|
||||||
|
**The `<version>` tag *must* be specified**. This is the version of the theming system the theme was designed for. The current version is 3.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
A *view* can be thought of as a particular "screen" within EmulationStation. Views are defined like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
<view name="ViewNameHere">
|
||||||
|
... define elements here ...
|
||||||
|
</view>
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
An *element* is a particular visual element, such as an image or a piece of text. You can either modify an element that already exists for a particular view (as is done in the "description" example), like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
<elementTypeHere name="ExistingElementNameHere">
|
||||||
|
... define properties here ...
|
||||||
|
</elementTypeHere>
|
||||||
|
```
|
||||||
|
|
||||||
|
Or, you can create your own elements by adding `extra="true"` (as is done in the "my_image" example) like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
<elementTypeHere name="YourUniqueElementNameHere" extra="true">
|
||||||
|
... define properties here ...
|
||||||
|
</elementTypeHere>
|
||||||
|
```
|
||||||
|
|
||||||
|
"Extra" elements will be drawn in the order they are defined. When they get drawn relative to the pre-existing elements depends on the view. Make sure "extra" element names do not clash with existing names.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
*Properties* control how a particular *element* looks - for example, its position, size, image path, etc. There different types of properties that determine what kinds of values you can use - you can read about them below in the "Reference" section. Properties are defined like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
<propertyNameHere>ValueHere</propertyNameHere>
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Advanced Features
|
||||||
|
=================
|
||||||
|
|
||||||
|
### The `<include>` tag
|
||||||
|
|
||||||
|
You can include theme files within theme files, similar to `#include` in C (though the mechanism is different, the effect is the same). Example:
|
||||||
|
|
||||||
|
`~/.emulationstation/all_themes.xml`:
|
||||||
|
```
|
||||||
|
<theme>
|
||||||
|
<version>3</version>
|
||||||
|
<view name="detailed">
|
||||||
|
<text name="description">
|
||||||
|
<fontPath>./all_themes/myfont.ttf</fontPath>
|
||||||
|
<color>00FF00</color>
|
||||||
|
</text>
|
||||||
|
</view>
|
||||||
|
</theme>
|
||||||
|
```
|
||||||
|
|
||||||
|
`~/.emulationstation/snes/theme.xml`:
|
||||||
|
```
|
||||||
|
<theme>
|
||||||
|
<version>3</version>
|
||||||
|
<include>./../all_themes.xml</include>
|
||||||
|
<view name="detailed">
|
||||||
|
<text name="description">
|
||||||
|
<color>FF0000</color>
|
||||||
|
</text>
|
||||||
|
</view>
|
||||||
|
</theme>
|
||||||
|
```
|
||||||
|
|
||||||
|
Is equivalent to this `snes/theme.xml`:
|
||||||
|
```
|
||||||
|
<theme>
|
||||||
|
<version>3</version>
|
||||||
|
<view name="detailed">
|
||||||
|
<text name="description">
|
||||||
|
<fontPath>./all_themes/myfont.ttf</fontPath>
|
||||||
|
<color>FF0000</color>
|
||||||
|
</text>
|
||||||
|
</view>
|
||||||
|
</theme>
|
||||||
|
```
|
||||||
|
|
||||||
|
Notice that properties that were not specified got merged (`<fontPath>`) and the `snes/theme.xml` could overwrite the included files' values (`<color>`). Also notice the included file still needed the `<version>` tag.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### The "common" view
|
||||||
|
|
||||||
|
Sometimes you want to apply the same values to the same element across many views. The "common" view is one way to do this.
|
||||||
|
|
||||||
|
```
|
||||||
|
<theme>
|
||||||
|
<version>3</version>
|
||||||
|
<view name="common">
|
||||||
|
<image name="header">
|
||||||
|
<path>./snes_art/snes_header.png</path>
|
||||||
|
</image>
|
||||||
|
</view>
|
||||||
|
<view name="detailed">
|
||||||
|
<image name="header">
|
||||||
|
<path>./snes_art/snes_header_detailed.png</path>
|
||||||
|
</image>
|
||||||
|
</view>
|
||||||
|
</theme>
|
||||||
|
```
|
||||||
|
|
||||||
|
Is equivalent to:
|
||||||
|
```
|
||||||
|
<theme>
|
||||||
|
<version>3</version>
|
||||||
|
<view name="basic">
|
||||||
|
<image name="header">
|
||||||
|
<path>./snes_art/snes_header.png</path>
|
||||||
|
</image>
|
||||||
|
</view>
|
||||||
|
<view name="detailed">
|
||||||
|
<image name="header">
|
||||||
|
<path>./snes_art/snes_header_detailed.png</path>
|
||||||
|
</image>
|
||||||
|
</view>
|
||||||
|
<view name="grid">
|
||||||
|
<image name="header">
|
||||||
|
<path>./snes_art/snes_header.png</path>
|
||||||
|
</image>
|
||||||
|
</view>
|
||||||
|
<view name="system">
|
||||||
|
<image name="header">
|
||||||
|
<path>./snes_art/snes_header.png</path>
|
||||||
|
</image>
|
||||||
|
</view>
|
||||||
|
... and any other view that might try to look up "header" ...
|
||||||
|
</theme>
|
||||||
|
```
|
||||||
|
|
||||||
|
Notice that you can still override the "common" view in a specific view definition (as shown in the "detailed" view).
|
||||||
|
|
||||||
|
You probably should not use the "common" view for element positioning. You also should not use it to create "extra" elements.
|
||||||
|
|
||||||
|
|
||||||
|
Reference
|
||||||
|
=========
|
||||||
|
|
||||||
|
## Views, their elements, and accepted properties:
|
||||||
|
|
||||||
|
#### basic
|
||||||
|
* image name="background" - PATH | TILING
|
||||||
|
* image name="header" - POSITION | SIZE | PATH
|
||||||
|
* textlist name="gamelist" - ALL
|
||||||
|
|
||||||
|
#### detailed
|
||||||
|
* image name="background" - PATH | TILING
|
||||||
|
* image name="header" - POSITION | SIZE | PATH
|
||||||
|
* textlist name="gamelist" - ALL
|
||||||
|
* image name="gameimage" - POSITION | SIZE
|
||||||
|
* container name="infoPanel" - POSITION | SIZE
|
||||||
|
* text name="description" - POSITION | FONT_PATH | FONT_SIZE | COLOR
|
||||||
|
|
||||||
|
#### grid
|
||||||
|
* image name="background" - PATH | TILING
|
||||||
|
* image name="header" - POSITION | SIZE | PATH
|
||||||
|
|
||||||
|
#### system
|
||||||
|
* image name="header" - PATH
|
||||||
|
* image name="system" - PATH
|
||||||
|
|
||||||
|
#### menu
|
||||||
|
* ninepatch name="background" - PATH
|
||||||
|
* textlist name="menulist" - FONT_PATH | COLOR | SOUND
|
||||||
|
* sound name="menuOpen" - PATH
|
||||||
|
* sound name="menuClose" - PATH
|
||||||
|
|
||||||
|
#### fastSelect
|
||||||
|
* ninepatch name="background" - PATH
|
||||||
|
* text name="letter" - FONT_PATH | COLOR
|
||||||
|
* text name="subtext" - FONT_PATH | COLOR
|
||||||
|
|
||||||
|
|
||||||
|
## Types of elements and their properties:
|
||||||
|
|
||||||
|
#### image
|
||||||
|
* `pos` - type: NORMALIZED_PAIR.
|
||||||
|
* `size` - type: NORMALIZED_PAIR.
|
||||||
|
* `origin` - type: NORMALIZED_PAIR.
|
||||||
|
* `path` - type: PATH.
|
||||||
|
* `tile` - type: BOOLEAN.
|
||||||
|
|
||||||
|
#### text
|
||||||
|
* `pos` - type: NORMALIZED_PAIR.
|
||||||
|
* `size` - type: NORMALIZED_PAIR.
|
||||||
|
* `text` - type: STRING.
|
||||||
|
* `color` - type: COLOR.
|
||||||
|
* `fontPath` - type: PATH.
|
||||||
|
* `fontSize` - type: FLOAT.
|
||||||
|
* `center` - type: BOOLEAN.
|
||||||
|
|
||||||
|
#### textlist
|
||||||
|
* `pos` - type: NORMALIZED_PAIR.
|
||||||
|
* `size` - type: NORMALIZED_PAIR.
|
||||||
|
* `selectorColor` - type: COLOR.
|
||||||
|
* `selectedColor` - type: COLOR.
|
||||||
|
* `primaryColor` - type: COLOR.
|
||||||
|
* `secondaryColor` - type: COLOR.
|
||||||
|
* `fontPath` - type: PATH.
|
||||||
|
* `fontSize` - type: FLOAT.
|
||||||
|
* `scrollSound` - type: PATH.
|
||||||
|
|
||||||
|
#### container
|
||||||
|
* `pos` - type: NORMALIZED_PAIR.
|
||||||
|
* `size` - type: NORMALIZED_PAIR.
|
||||||
|
|
||||||
|
#### ninepatch
|
||||||
|
* `pos` - type: NORMALIZED_PAIR.
|
||||||
|
* `size` - type: NORMALIZED_PAIR.
|
||||||
|
* `path` - type: PATH.
|
||||||
|
|
||||||
|
A quick word on the "ninepatch" type - EmulationStation borrows the concept of "nine patches" from Android (or "9-Slices"). Currently the implementation is very simple and hard-coded to only use 48x48px images (16x16px for each "patch"). Check the `data/resources` directory for some examples (button.png, frame.png).
|
||||||
|
|
||||||
|
#### sound
|
||||||
|
* `path` - type: PATH.
|
||||||
|
|
||||||
|
|
||||||
|
*Note that a view may choose to only make only certain properties on a particular element themable.*
|
||||||
|
|
||||||
|
|
||||||
|
## Types of properties:
|
||||||
|
|
||||||
|
* NORMALIZED_PAIR - two decimals, in the range [0..1]. For example, `0.25 0.5`.
|
||||||
|
* PATH - a path. If the first character is a `~`, it will be expanded into the environment variable for the home path (`$HOME` or `%HOMEPATH%`, depending on platform). If the first character is a `.`, it will be expanded to the theme file's directory.
|
||||||
|
* 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).
|
||||||
|
* FLOAT - a decimal.
|
||||||
|
* STRING - a string of text.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
-Aloshi
|
-Aloshi
|
||||||
http://www.aloshi.com
|
http://www.aloshi.com
|
||||||
|
|
|
||||||
|
|
@ -38,6 +38,10 @@ std::map< std::string, std::map<std::string, ThemeData::ElementPropertyType> > T
|
||||||
("container", boost::assign::map_list_of
|
("container", boost::assign::map_list_of
|
||||||
("pos", NORMALIZED_PAIR)
|
("pos", NORMALIZED_PAIR)
|
||||||
("size", NORMALIZED_PAIR))
|
("size", NORMALIZED_PAIR))
|
||||||
|
("ninepatch", boost::assign::map_list_of
|
||||||
|
("pos", NORMALIZED_PAIR)
|
||||||
|
("size", NORMALIZED_PAIR)
|
||||||
|
("path", PATH))
|
||||||
("sound", boost::assign::map_list_of
|
("sound", boost::assign::map_list_of
|
||||||
("path", PATH));
|
("path", PATH));
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue