diff --git a/THEMES.md b/THEMES.md index e9fca7010..a787436cf 100644 --- a/THEMES.md +++ b/THEMES.md @@ -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: ``` - 0000FF - 00FF00 - - - ./../all_themes/font.ttf - 0.045 - - - - ./../all_themes/font.ttf - 0.035 - - - - ./theme/background.png - true - - - - ./theme/logo.png - false - - - ./../all_themes/scrollSound.wav + 3 + + + 00FF00 + + + 0.5 0.5 + 0.5 0.5 + 0.8 0.8 + ./my_art/my_awesome_image.jpg + + ``` -Themes must be enclosed in a `` 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: -``` - - - ./some/path/here.ttf - - 0.035 - -``` - - -`` - Default size: 0.045. - -`` - Default size: 0.035. - -`` - Default size: 0.15. - -Colors -====== - -Colors are defined in hex, like this: - -`00FF00FF` - -or - -`00FF00` - -(without the alpha channel specified - will assume FF) - - -`` - Default: 0000FFFF. - -`` - Default: 00FF00FF. - -`` - Default: 000000FF. - -`` - Default: 00000000. - -`` - Default: 48474DFF. - -`` - Default: FFFFFFFF. - -`` - Default: DDDDDDFF. - -Images -====== - -Images are defined like this: -``` - - ./some/path/here.png - - true - -``` -Pretty much any image format is supported. - - -`` - No default. - -`` - No default. - -`` - No default. - -`` - No default. - -`` - No default. Large image, shown in the system select menu. - -`` - Nine patch. Default is the "button.png" resource. - -Sounds -====== - -Sounds are defined like this: - -`./some/path/here.wav` - -Only .wav files are supported. - - -`` - No default. Played when a list scrolls. - -`` - No default. Played when a game is launched. - -`` - No default. Played when leaving a folder in the game list. - -`` - No default. Played when the menu is opened. - -`` - 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 `` tag. + +**The `` 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: + +``` + + ... define elements here ... + +``` + + + +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: + +``` + + ... define properties here ... + +``` + +Or, you can create your own elements by adding `extra="true"` (as is done in the "my_image" example) like this: + +``` + + ... define properties here ... + +``` + +"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: + +``` + ValueHere +``` + + + + +Advanced Features +================= + +### The `` 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`: +``` + + 3 + + + ./all_themes/myfont.ttf + 00FF00 + + + +``` + +`~/.emulationstation/snes/theme.xml`: +``` + + 3 + ./../all_themes.xml + + + FF0000 + + + +``` + +Is equivalent to this `snes/theme.xml`: +``` + + 3 + + + ./all_themes/myfont.ttf + FF0000 + + + +``` + +Notice that properties that were not specified got merged (``) and the `snes/theme.xml` could overwrite the included files' values (``). Also notice the included file still needed the `` 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. + +``` + + 3 + + + ./snes_art/snes_header.png + + + + + ./snes_art/snes_header_detailed.png + + + +``` + +Is equivalent to: +``` + + 3 + + + ./snes_art/snes_header.png + + + + + ./snes_art/snes_header_detailed.png + + + + + ./snes_art/snes_header.png + + + + + ./snes_art/snes_header.png + + + ... and any other view that might try to look up "header" ... + +``` + +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 diff --git a/src/ThemeData.cpp b/src/ThemeData.cpp index 32696e952..b885877ce 100644 --- a/src/ThemeData.cpp +++ b/src/ThemeData.cpp @@ -38,6 +38,10 @@ std::map< std::string, std::map > 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));