THEMES.md 29.3 KB
Newer Older
root's avatar
root committed
1 2 3
Themes
======

4
EmulationStation allows each system to have its own "theme." A theme is a collection **views** that define some **elements**, each with their own **properties**.
root's avatar
root committed
5

6
The first place ES will check for a theme is in the system's `<path>` folder, for a theme.xml file:
7
* `[SYSTEM_PATH]/theme.xml`
8

9 10 11 12 13
Then it will check for * `[CURRENT_THEME_PATH]/[SYSTEM]/theme.xml`

and finally in :

* `[CURRENT_THEME_PATH]/theme.xml`
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

```
...
   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.

There are two places ES can load theme sets from:
39
* `[HOME]/.emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml`
40
* `/etc/emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml` (please note that in Recalbox, `/etc/emulationstation/` points to SHARE_INIT that is read only)
41 42

`[SYSTEM_THEME]` is the `<theme>` tag for the system, as defined in `es_systems.cfg`.  If the `<theme>` tag is not set, ES will use the system's `<name>`.
43 44 45 46

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.
47

48 49
Simple Example
==============
50

51
Here is a very simple theme that changes the description text's color:
root's avatar
root committed
52

Aloshi's avatar
Aloshi committed
53
```xml
root's avatar
root committed
54
<theme>
55
	<formatVersion>3</formatVersion>
56 57 58 59 60 61 62 63 64 65 66
	<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>
67 68
</theme>
```
69

70 71 72 73
How it works
============

Everything must be inside a `<theme>` tag.
74

75
**The `<formatVersion>` tag *must* be specified**.  This is the version of the theming system the theme was designed for.  The current version is 4.
76

77

Aloshi's avatar
Aloshi committed
78

79
A *view* can be thought of as a particular "screen" within EmulationStation.  Views are defined like this:
Aloshi's avatar
Aloshi committed
80

Aloshi's avatar
Aloshi committed
81
```xml
82 83 84
<view name="ViewNameHere">
	... define elements here ...
</view>
Aloshi's avatar
Aloshi committed
85 86
```

87 88


89
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:
90

Aloshi's avatar
Aloshi committed
91
```xml
92 93 94 95
	<elementTypeHere name="ExistingElementNameHere">
		... define properties here ...
	</elementTypeHere>
```
Aloshi's avatar
Aloshi committed
96

97
Or, you can create your own elements by adding `extra="true"` (as is done in the "my_image" example) like this:
Aloshi's avatar
Aloshi committed
98

Aloshi's avatar
Aloshi committed
99
```xml
100 101 102 103
	<elementTypeHere name="YourUniqueElementNameHere" extra="true">
		... define properties here ...
	</elementTypeHere>
```
Aloshi's avatar
Aloshi committed
104

105
"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_".
106 107 108



109
*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:
Aloshi's avatar
Aloshi committed
110

Aloshi's avatar
Aloshi committed
111
```xml
112 113
		<propertyNameHere>ValueHere</propertyNameHere>
```
114 115 116 117




118 119
Advanced Features
=================
120

121
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.
122

123
### The `<include>` tag
124

125
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:
126

127
`~/.emulationstation/all_themes.xml`:
Aloshi's avatar
Aloshi committed
128
```xml
129
<theme>
130
	<formatVersion>3</formatVersion>
131 132 133 134 135 136 137 138
	<view name="detailed">
		<text name="description">
			<fontPath>./all_themes/myfont.ttf</fontPath>
			<color>00FF00</color>
		</text>
	</view>
</theme>
```
139

140
`~/.emulationstation/snes/theme.xml`:
Aloshi's avatar
Aloshi committed
141
```xml
142
<theme>
143
	<formatVersion>3</formatVersion>
144 145 146 147 148 149 150 151
	<include>./../all_themes.xml</include>
	<view name="detailed">
		<text name="description">
			<color>FF0000</color>
		</text>
	</view>
</theme>
```
152

153
Is equivalent to this `snes/theme.xml`:
Aloshi's avatar
Aloshi committed
154
```xml
155
<theme>
156
	<formatVersion>3</formatVersion>
157 158 159 160 161 162 163
	<view name="detailed">
		<text name="description">
			<fontPath>./all_themes/myfont.ttf</fontPath>
			<color>FF0000</color>
		</text>
	</view>
</theme>
164
```
165

166
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 `<formatVersion>` tag.
167

168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
### Change configurable theme elements within ES

You can add name and subset attributes in `<include>` tag, that way, you can have several different includes that are configurable directly in ES.

`~/.emulationstation/all_themes.xml`:
```xml
<theme>
	<formatVersion>4</formatVersion>
	<include name="nice colors" subset="colorset">./../nice_colors.xml</include>
	<include name="other colors" subset="colorset">./../other_colors.xml</include>
	<include name="nice systemview" subset="systemview">./../nice_sys.xml</include>
	<include name="new carousel" subset="systemview">./../carousel.xml</include>
	<include name="nice gamelist" subset="gamelistview">./../game.xml</include>
	<include name="ugly gamelist" subset="gamelistview">./../ugly.xml</include>
</theme>
```

name must be unique among all includes.
subset must be "colorset", "iconset", "menu", "systemview" or "gamelistview".
the selected options are stored in es_settings.cfg once selected in the menus.
188 189


190
### Theming multiple views simultaneously
191

192
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:
193

Aloshi's avatar
Aloshi committed
194
```xml
195
<theme>
196
	<formatVersion>3</formatVersion>
197
	<view name="basic, grid, system">
198
		<image name="logo">
199 200 201 202
			<path>./snes_art/snes_header.png</path>
		</image>
	</view>
	<view name="detailed">
203
		<image name="logo">
204 205 206 207 208
			<path>./snes_art/snes_header_detailed.png</path>
		</image>
	</view>
</theme>
```
209

210
This is equivalent to:
Aloshi's avatar
Aloshi committed
211
```xml
212
<theme>
213
	<formatVersion>3</formatVersion>
214
	<view name="basic">
215
		<image name="logo">
216 217 218 219
			<path>./snes_art/snes_header.png</path>
		</image>
	</view>
	<view name="detailed">
220
		<image name="logo">
221 222 223 224
			<path>./snes_art/snes_header_detailed.png</path>
		</image>
	</view>
	<view name="grid">
225
		<image name="logo">
226 227 228 229
			<path>./snes_art/snes_header.png</path>
		</image>
	</view>
	<view name="system">
230
		<image name="logo">
231 232 233
			<path>./snes_art/snes_header.png</path>
		</image>
	</view>
234
	... and any other view that might try to look up "logo" ...
235 236
</theme>
```
237 238


239

240
### Theming multiple elements simultaneously
241

242
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:
243 244 245

```xml
<theme>
246
    <formatVersion>3</formatVersion>
247
    <view name="detailed">
Aloshi's avatar
Aloshi committed
248
    	<!-- Weird spaces/newline on purpose! -->
249 250 251 252 253 254 255 256
    	<text name="md_lbl_rating, md_lbl_releasedate, md_lbl_developer, md_lbl_publisher, 
    	md_lbl_genre,    md_lbl_players,        md_lbl_lastplayed, md_lbl_playcount">
        	<color>48474D</color>
        </text>
    </view>
</theme>
```

257
Which is equivalent to:
258 259
```xml
<theme>
260
    <formatVersion>3</formatVersion>
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285
    <view name="detailed">
    	<text name="md_lbl_rating">
    		<color>48474D</color>
    	</text>
    	<text name="md_lbl_releasedate">
    		<color>48474D</color>
    	</text>
    	<text name="md_lbl_developer">
    		<color>48474D</color>
    	</text>
    	<text name="md_lbl_publisher">
    		<color>48474D</color>
    	</text>
    	<text name="md_lbl_genre">
    		<color>48474D</color>
    	</text>
    	<text name="md_lbl_players">
    		<color>48474D</color>
    	</text>
    	<text name="md_lbl_lastplayed">
    		<color>48474D</color>
    	</text>
    	<text name="md_lbl_playcount">
    		<color>48474D</color>
    	</text>
digitalLumberjack's avatar
digitalLumberjack committed
286 287 288
    	<text name="md_lbl_favorite">
    		<color>48474D</color>
    	</text>
289 290 291 292 293 294
    </view>
</theme>
```

Just remember, *this only works if the elements have the same type!*

295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385
### Element rendering order with z-index
 
 You can now change the order in which elements are rendered by setting `zIndex` values.  Default values correspond to the default rendering order while allowing elements to easily be shifted without having to set `zIndex` values for every element.  Elements will be rendered in order from smallest z-index to largest.
 
 #### Defaults
 
 ##### system
 * Extra Elements `extra="true"` - 10
 * `carousel name="systemcarousel"` - 40
 * `text name="systemInfo"` - 50
 
 ##### basic, detailed, video
 * `image name="background"` - 0
 * Extra Elements `extra="true"` - 10
 * `textlist name="gamelist"` - 20
 * Media
 	* `image name="md_image"` - 30
 	* `video name="md_video"` - 30
 	* `image name="md_marquee"` - 35
 * Metadata - 40
 	* Labels
 		* `text name="md_lbl_rating"`
 		* `text name="md_lbl_releasedate"`
 		* `text name="md_lbl_developer"`
 		* `text name="md_lbl_publisher"`
 		* `text name="md_lbl_genre"`
 		* `text name="md_lbl_players"`
 		* `text name="md_lbl_lastplayed"`
 		* `text name="md_lbl_playcount"`
 	* Values
 		* `rating name="md_rating"`
 		* `datetime name="md_releasedate"`
 		* `text name="md_developer"`
 		* `text name="md_publisher"`
 		* `text name="md_genre"`
 		* `text name="md_players"`
 		* `datetime name="md_lastplayed"`
 		* `text name="md_playcount"`
 		* `text name="md_description"`
 * System Logo/Text - 50
 	* `text name="logoText"`
 	* `image name="logo"`
 
### Region based elements

you can add a region property in any element so that user can choose in ES which ones will be displayed.


```
<image name="logo" region="eu">
	<path>./snes_art/snes_eu.png</path>
</image>
<image name="logo" region="jp">
	<path>./snes_art/snes_jp.png</path>
</image>
<image name="logo" region="us">
	<path>./snes_art/snes_us.png</path>
</image>
```

in this example, if user set ES option to jp, only the second logo will be used.
Selected option is stored in es_settings.cfg.

### System variable

You can use a special name (variable) in paths for images, fonts and even <include> tags that ES will replace with the correct path found in es_systems.cfg.

```
<image name="logo">
	<path>./$system/logo.png</path>
</image>
<include>./$system/myxml.xml</include>
```

will transform in:

```
<image name="logo">
	<path>./nes/logo.png</path>
</image>
<include>./nes/myxml.xml</include>
```

```
<image name="logo">
	<path>./mame/logo.png</path>
</image>
<include>./mame/myxml.xml</include>
```

and so on.
386

387 388
Reference
=========
389

390
## Views, their elements, and themable properties:
391

392
#### basic
Aloshi's avatar
Aloshi committed
393 394
* `helpsystem name="help"` - ALL
	- The help system style for this view.
395 396
* `image name="background"` - ALL
	- This is a background image that exists for convenience. It goes from (0, 0) to (1, 1).
397 398 399
* `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.
* `image name="logo"` - ALL
400 401 402 403 404
	- 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.

---
405

406
#### detailed
Aloshi's avatar
Aloshi committed
407 408
* `helpsystem name="help"` - ALL
	- The help system style for this view.
409 410
* `image name="background"` - ALL
	- This is a background image that exists for convenience. It goes from (0, 0) to (1, 1).
411 412 413
* `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.
* `image name="logo"` - ALL
414 415 416 417 418 419 420 421 422 423 424 425 426 427
	- 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
digitalLumberjack's avatar
digitalLumberjack committed
428
      * `text name="md_lbl_favorite"` - ALL
429 430 431 432

	* Values
		* All values will follow to the right of their labels if a position isn't specified.

433
		* `image name="md_image"` - POSITION | SIZE | Z_INDEX
Aloshi's avatar
Aloshi committed
434
			- Path is the "image" metadata for the currently selected game.
435
		* `rating name="md_rating"` - ALL
Aloshi's avatar
Aloshi committed
436
			- The "rating" metadata.
437
		* `datetime name="md_releasedate"` - ALL
Aloshi's avatar
Aloshi committed
438
			- The "releasedate" metadata.
439
		* `text name="md_developer"` - ALL
Aloshi's avatar
Aloshi committed
440
			- The "developer" metadata.
441
		* `text name="md_publisher"` - ALL
Aloshi's avatar
Aloshi committed
442
			- The "publisher" metadata.
443
		* `text name="md_genre"` - ALL
Aloshi's avatar
Aloshi committed
444
			- The "genre" metadata.
445
		* `text name="md_players"` - ALL
Aloshi's avatar
Aloshi committed
446
			- The "players" metadata (number of players the game supports).
447
		* `datetime name="md_lastplayed"` - ALL
Aloshi's avatar
Aloshi committed
448
			- The "lastplayed" metadata.  Displayed as a string representing the time relative to "now" (e.g. "3 hours ago").
449
		* `text name="md_playcount"` - ALL
Aloshi's avatar
Aloshi committed
450
			- The "playcount" metadata (number of times the game has been played).
digitalLumberjack's avatar
digitalLumberjack committed
451 452
		* `text name="md_favorite"` - ALL
			- The "favorite" metadata (is this game a favorite).
453
		* `text name="md_description"` - POSITION | SIZE | FONT_PATH | FONT_SIZE | COLOR | Z_INDEX
Aloshi's avatar
Aloshi committed
454
			- 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.
455 456

---
457

458
#### grid
Aloshi's avatar
Aloshi committed
459 460
* `helpsystem name="help"` - ALL
	- The help system style for this view.
461 462
* `image name="background"` - ALL
	- This is a background image that exists for convenience. It goes from (0, 0) to (1, 1).
463 464 465
* `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.
* `image name="logo"` - ALL
466 467 468
	- 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.

---
469

470
#### system
Aloshi's avatar
Aloshi committed
471 472
* `helpsystem name="help"` - ALL
	- The help system style for this view.
473 474
* `carousel name="systemcarousel"` -ALL
	- The system logo carousel
475 476
* `image name="logo"` - PATH
	- A logo image, to be displayed in the system logo carousel.
477 478
* `text name="systemInfo"` - ALL
	- Displays details of the system currently selected in the carousel.
479
* 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.
480

481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504
---

#### menu
* `helpsystem name="help"` - ALL
	- The help system style for this view. If not defined, menus will have the same helpsystem as defined in system view.
* `menuBackground name="menubg"` - COLOR | PATH | FADEPATH
	- The background behind menus. you can set an image and/or change color (alpha supported)
	
* `menuSwitch name="menuswitch"` - PATHON | PATHOFF
	- Images for the on/off switch in menus
* `menuSlider name="menuslider"` - PATH
	- Image for the slider knob in menus
* `menuButton name="menubutton"` - PATH | FILLEDPATH
	- Images for menu buttons
* `menuText name="menutext"` - FONTPATH | FONTSIZE | COLOR
	- text for all menu entries
* `menuText name="menutitle"` - FONTPATH | FONTSIZE | COLOR
	- text for menu titles
* `menuText name="menufooter"` - FONTPATH | FONTSIZE | COLOR
	- text for menu footers or subtitles
* `menuTextSmall name="menutextsmall"` - FONTPATH | FONTSIZE | COLOR
	- text for menu entries in smallerfont
	
menu is used to theme helpsystem and ES menus.
505

Aloshi's avatar
Aloshi committed
506 507
## Types of properties:

508
* 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).
509
* 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`.
Aloshi's avatar
Aloshi committed
510 511 512 513 514 515
* 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.


516 517
## Types of elements and their properties:

518 519 520 521
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!
522
*Note that a view may choose to only make only certain properties on a particular element themable!*
523

524
#### image
525 526 527 528 529

Can be created as an extra.

* `pos` - type: NORMALIZED_PAIR.
* `size` - type: NORMALIZED_PAIR.
530
	- 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.
531 532 533
* `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).
* `origin` - type: NORMALIZED_PAIR.
534
	- 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.
535 536 537 538
* `rotation` - type: FLOAT.
	- angle in degrees that the image should be rotated.  Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR.
	- Point around which the image will be rotated. Defaults to `0.5 0.5`.
539 540 541 542
* `path` - type: PATH.
	- Path to the image file.  Most common extensions are supported (including .jpg, .png, and unanimated .gif).
* `tile` - type: BOOLEAN.
	- If true, the image will be tiled instead of stretched to fit its size.  Useful for backgrounds.
543
* `color` - type: COLOR.
544
	- 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.
545 546 547
* `zIndex` - type: FLOAT.
	- z-index value for component.  Components will be rendered in order of z-index value from low to high.
	
548
#### text
549 550 551 552 553

Can be created as an extra.

* `pos` - type: NORMALIZED_PAIR.
* `size` - type: NORMALIZED_PAIR.
554 555 556 557
	- Possible combinations:
	- `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 (...).
558 559 560 561 562 563
* `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 themable, "ORIGIN" is implied.
* `rotation` - type: FLOAT.
	- angle in degrees that the text should be rotated.  Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR.
	- Point around which the text will be rotated. Defaults to `0.5 0.5`.
564 565 566 567 568 569
* `text` - type: STRING.
* `color` - type: COLOR.
* `fontPath` - type: PATH.
	- Path to a truetype font (.ttf).
* `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).
570 571
* `alignment` - type: STRING.
	- Valid values are "left", "center", or "right".  Controls alignment on the X axis.  "center" will also align vertically.
572
* `forceUppercase` - type: BOOLEAN.  Draw text in uppercase.
573
* `lineSpacing` - type: FLOAT.  Controls the space between lines (as a multiple of font height).  Default is 1.5.
574 575
* `zIndex` - type: FLOAT.
	- z-index value for component.  Components will be rendered in order of z-index value from low to high.
576 577

#### textlist
578 579 580

* `pos` - type: NORMALIZED_PAIR.
* `size` - type: NORMALIZED_PAIR.
581 582
* `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 themable, "ORIGIN" is implied.
583 584
* `selectorColor` - type: COLOR.
	- Color of the "selector bar."
585 586 587 588 589 590 591 592
* `selectorImagePath` - type: PATH.
	- Path to image to render in place of "selector bar."
* `selectorImageTile` - type: BOOLEAN.
	- If true, the selector image will be tiled instead of stretched to fit its size.
* `selectorHeight` - type: FLOAT.
	- Height of the "selector bar".
* `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.
593 594 595 596 597 598 599 600 601 602
* `selectedColor` - type: COLOR.
	- Color of the highlighted entry text.
* `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.
* `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.
* `fontPath` - type: PATH.
* `fontSize` - type: FLOAT.
* `scrollSound` - type: PATH.
	- Sound that is played when the list is scrolled.
603 604 605 606
* `alignment` - type: STRING.
	- 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).
607
* `forceUppercase` - type: BOOLEAN.  Draw text in uppercase.
608
* `lineSpacing` - type: FLOAT.  Controls the space between lines (as a multiple of font height).  Default is 1.5.
609 610
* `zIndex` - type: FLOAT.
	- z-index value for component.  Components will be rendered in order of z-index value from low to high.
611 612 613

#### ninepatch

614 615 616
* `pos` - type: NORMALIZED_PAIR.
* `size` - type: NORMALIZED_PAIR.
* `path` - type: PATH.
617 618
* `zIndex` - type: FLOAT.
	- z-index value for component.  Components will be rendered in order of z-index value from low to high.
619 620

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).
621

622 623 624 625 626
#### rating

* `pos` - 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.)
627 628 629 630 631 632
* `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 themable, "ORIGIN" is implied.
* `rotation` - type: FLOAT.
	- angle in degrees that the rating should be rotated.  Positive values will rotate clockwise, negative values will rotate counterclockwise.
* `rotationOrigin` - type: NORMALIZED_PAIR.
	- Point around which the rating will be rotated. Defaults to `0.5 0.5`.
633 634 635 636
* `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).
637 638
* `zIndex` - type: FLOAT.
	- z-index value for component.  Components will be rendered in order of z-index value from low to high.
639 640 641 642 643 644 645 646 647

#### datetime

* `pos` - type: NORMALIZED_PAIR.
* `size` - type: NORMALIZED_PAIR.
	- You should probably not set this.  Leave it to `fontSize`.
* `color` - type: COLOR.
* `fontPath` - type: PATH.
* `fontSize` - type: FLOAT.
648
* `forceUppercase` - type: BOOLEAN.  Draw text in uppercase.
649

650
#### sound
651 652 653

* `path` - type: PATH.
	- Path to the sound file.  Only .wav files are currently supported.
654

Aloshi's avatar
Aloshi committed
655 656
#### helpsystem

657
* `pos` - type: NORMALIZED_PAIR.  Default is "0.012 0.9515"
658 659
* `textColor` - type: COLOR.  Default is 777777FF.
* `iconColor` - type: COLOR.  Default is 777777FF.
Aloshi's avatar
Aloshi committed
660 661
* `fontPath` - type: PATH.
* `fontSize` - type: FLOAT.
662 663 664 665 666 667 668 669 670 671 672 673 674 675 676
* `iconUpDown` - type: PATH.
* `iconLeftRight` - type: PATH.
* `iconUpDownLeftRight` - type: PATH.
* `iconA` - type: PATH.
* `iconB` - type: PATH.
* `iconX` - type: PATH.
* `iconY` - type: PATH.
* `iconL` - type: PATH.
* `iconR` - type: PATH.
* `iconStart` - type: PATH.
* `iconSelect` - type: PATH.

#### carousel

* `type` - type: STRING.
John Rassa's avatar
John Rassa committed
677 678 679
	- Sets the scoll direction of the carousel.
    - Accepted values are "horizontal", "vertical" or "vertical_wheel".
    - Default is "horizontal".
680 681
* `size` - type: NORMALIZED_PAIR. Default is "1 0.2325"
* `pos` - type: NORMALIZED_PAIR.  Default is "0 0.38375".
John Rassa's avatar
John Rassa committed
682 683
* `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 themable, "ORIGIN" is implied.
684 685 686 687 688
* `color` - type: COLOR.
	- Controls the color of the carousel background.
	- Default is FFFFFFD8
* `logoSize` - type: NORMALIZED_PAIR.  Default is "0.25 0.155"
* `logoScale` - type: FLOAT.
John Rassa's avatar
John Rassa committed
689 690 691 692 693 694 695 696 697 698 699 700 701 702
 - Selected logo is increased in size by this scale
 	- Default is 1.2
 * `logoRotation` - type: FLOAT.
 	- Angle in degrees that the logos should be rotated.  Value should be positive.
 	- Default is 7.5
 	- This property only applies when `type` is "vertical_wheel".
 * `logoRotationOrigin` - type: NORMALIZED_PAIR.
 	- Point around which the logos will be rotated. Defaults to `-5 0.5`.
 	- This property only applies when `type` is "vertical_wheel".
 * `logoAlignment` - type: STRING.
 	- Sets the alignment of the logos relative to the carousel.
 	- Accepted values are "top", "bottom" or "center" when `type` is "horizontal".
 	- Accepted values are "left", "right" or "center" when `type` is "vertical" or "vertical_wheel".
 	- Default is "center"
703 704 705
* `maxLogoCount` - type: FLOAT.
	- Sets the number of logos to display in the carousel.
	- Default is 3
706 707 708
* `defaultTransition` - type: STRING.
    - Force transition style.
    - Accepted values are "instant", "fade" or "slide".
709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726
* `zIndex` - type: FLOAT.
	- z-index value for component.  Components will be rendered in order of z-index value from low to high.
	
#### menuText & menuTextSmall

* `color` - type: COLOR. 
	- Default is 777777FF
* `fontPath` - type: PATH.
	- Path to a truetype font (.ttf).
* `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). Default is 0.085 for menutitle, 0.045 for menutext and 0.035 for menufooter and menutextsmall.
* `separatorColor` - type: COLOR. 
	- Default is C6C7C6FF. Color of lines that separates menu entries.
* `selectedColor` - type: COLOR. 
	- Default is FFFFFFFF. Color of text for selected menu entry.
* `selectorColor` - type: COLOR. 
	- Default is 878787FF. Color of the selector bar.
	
727

Aloshi's avatar
Aloshi committed
728
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.
729

Aloshi's avatar
Aloshi committed
730
[*Check out the "official" themes for some more examples!*](http://aloshi.com/emulationstation#themes)