EmulationStation allows each system to have its own "theme." A theme is a collection **views** that define some **elements**, each with their own **properties**.
If that file doesn't exist, ES will try to find the theme in the current **theme set**. Theme sets are just a collection of individual system themes arranged in the "themes" folder under some name. Here's an example:
```
...
themes/
my_theme_set/
snes/
theme.xml
my_cool_background.jpg
nes/
theme.xml
my_other_super_cool_background.jpg
common_resources/
scroll_sound.wav
another_theme_set/
snes/
theme.xml
some_resource.svg
```
The theme set system makes it easy for users to try different themes and allows distributions to include multiple theme options. Users can change the currently active theme set in the "UI Settings" menu. The option is only visible if at least one theme set exists.
If both files happen to exist, ES will pick the first one (the one located in the home directory).
Again, the `[CURRENT_THEME_SET]` value is set in the "UI Settings" menu. If it has not been set yet or the previously selected theme set is missing, the first available theme set will be used as the default.
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:
"Extra" elements will be drawn in the order they are defined (so define backgrounds first!). When they get drawn relative to the pre-existing elements depends on the view. Make sure "extra" element names do not clash with existing element names! An easy way to protect against this is to just start all your extra element names with some prefix like "e_".
*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:
It is recommended that if you are writing a theme you launch EmulationStation with the `--debug` and `--windowed` switches. This way you can read error messages without having to check the log file. You can also reload the current gamelist view and system view with `Ctrl-R` if `--debug` is specified.
You can include theme files within theme files, similar to `#include` in C (though the internal mechanism is different, the effect is the same). Example:
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.
Sometimes you want to apply the same properties to the same elements across multiple views. The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas). So, for example, to easily apply the same header to the basic, grid, and system views:
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), just like it does for views, as long as the elements have the same type. This is useful if you want to, say, apply the same color to all the metadata labels:
- A header image. If a non-empty `path` is specified, `text name="headerText"` will be hidden and this image will be, by default, displayed roughly in its place.
*`textlist name="gamelist"` - ALL
- The gamelist. `primaryColor` is for games, `secondaryColor` is for folders. Centered by default.
- A header image. If a non-empty `path` is specified, `text name="headerText"` will be hidden and this image will be, by default, displayed roughly in its place.
*`textlist name="gamelist"` - ALL
- The gamelist. `primaryColor` is for games, `secondaryColor` is for folders. Left aligned by default.
* Metadata
* Labels
*`text name="md_lbl_rating"` - ALL
*`text name="md_lbl_releasedate"` - ALL
*`text name="md_lbl_developer"` - ALL
*`text name="md_lbl_publisher"` - ALL
*`text name="md_lbl_genre"` - ALL
*`text name="md_lbl_players"` - ALL
*`text name="md_lbl_lastplayed"` - ALL
*`text name="md_lbl_playcount"` - ALL
* Values
* All values will follow to the right of their labels if a position isn't specified.
- 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.
- A header image. If a non-empty `path` is specified, `text name="headerText"` will be hidden and this image will be, by default, displayed roughly in its place.
* You can use extra elements (elements with `extra="true"`) to add your own backgrounds, etc. They will be displayed behind the carousel, and scroll relative to the carousel.
* 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).
* PATH - a path. If the first character is a `~`, it will be expanded into the environment variable for the home path (`$HOME` for Linux or `%HOMEPATH%` for Windows). If the first character is a `.`, it will be expanded to the theme file's directory, allowing you to specify resources relative to the theme file, like so: `./../general_art/myfont.ttf`.
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.
Remember, you do *not* need to specify every property!
- 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).
- 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 themable, "ORIGIN" is implied.
- 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.
-`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 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 (...).
- Valid values are "left", "center", or "right". Controls alignment on the X axis.
*`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).
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).
- 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.)
*`filledPath` - type: PATH.
- Path to the "filled star" image. Image must be square (width equals height).
*`unfilledPath` - type: PATH.
- Path to the "unfilled star" image. Image must be square (width equals height).
#### datetime
*`pos` - type: NORMALIZED_PAIR.
*`size` - type: NORMALIZED_PAIR.
- You should probably not set this. Leave it to `fontSize`.
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.
