EmulationStation allows each system to have its own "theme." A theme is a collection **views** that define some **elements**, each with their own **properties**.
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. 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:
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 with `Ctrl-R` if `--debug` is specified.
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.
You can theme multiple elements *of the same type* simultaneously. The `name` attribute actually works as a list (delimited by any characters of `\t\n ,` - that is, whitespace and commas). This is useful if you want to, say, apply the same color to all the metadata labels:
- This is a background image that exists for convenience. It goes from (0, 0) to (1, 1).
*`text name="headerText"` - ALL
- A header text, which displays the name of the system. Displayed at the top center of the screen. Centered by default.
*`image name="header"` - ALL
- 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.
- This is a background image that exists for convenience. It goes from (0, 0) to (1, 1).
*`text name="headerText"` - ALL
- A header text, which displays the name of the system. Displayed at the top center of the screen. Centered by default.
*`image name="header"` - ALL
- 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.
- This is a background image that exists for convenience. It goes from (0, 0) to (1, 1).
*`text name="headerText"` - ALL
- A header text, which displays the name of the system. Displayed at the top center of the screen. Centered by default.
*`image name="header"` - ALL
- 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` 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).
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.
-`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`.
