Xargon/ES-DE
1
0
Fork 0
mirror of https://github.com/RetroDECK/ES-DE.git synced 2025-04-10 19:15:13 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Rewrote the theming documentation.

Browse source
This commit is contained in:
Aloshi 2014-01-06 13:27:34 -06:00
parent 8d1ac3087e
commit 5a84bc03ea
2 changed files with 264 additions and 139 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

399
THEMES.md
View file

@ -1,156 +1,277 @@
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.
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.
Simple Example
==============
IF NOT, If `$HOME/.emulationstation/%SYSTEMNAME%/theme.xml` exists, load it.
Example
=======
Here is a very simple theme that changes the description text's color:
```
<theme>
<listPrimaryColor>0000FF</listPrimaryColor>
<listSecondaryColor>00FF00</listSecondaryColor>
<listFont>
<path>./../all_themes/font.ttf</path>
<size>0.045</size>
</listFont>
<descriptionFont>
<path>./../all_themes/font.ttf</path>
<size>0.035</size>
</descriptionFont>
<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>
<version>3</version>
<view name="detailed">
<text name="description">
<color>00FF00</color>
</text>
<image name="my_image" extra="true">
<pos>0.5 0.5</pos>
<origin>0.5 0.5</origin>
<size>0.8 0.8</size>
<path>./my_art/my_awesome_image.jpg</path>
</image>
</view>
</theme>
```
Themes must be enclosed in a `<theme>` tag.
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
How it works
============
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
http://www.aloshi.com

4
src/ThemeData.cpp
View file

@ -38,6 +38,10 @@ std::map< std::string, std::map<std::string, ThemeData::ElementPropertyType> > T
("container", boost::assign::map_list_of
("pos", 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
("path", PATH));