RetroFE Documentation

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== General Layout Information ======

Layouts define the look and feel for your frontend. Each layout is a folder containing at least the following two main files.

\\
=====Directory Structure=====
^Path ^Description^
|/layouts/<layout name>/| Folder to store all image files for a particular asset. i.e. <layout name> = "Default 16x9"|
| /layouts/<layout name>/splash.xml| Splash screen to show at startup|
| /layouts/<layout name>/layout.xml| Main layout file to show when frontend is loaded|

[[https://bitbucket.org/teamretro/retrofe/src/default/Package/Environment/Common/layouts/Default%2016x9|An example of a layout]]
[[https://bitbucket.org/teamretro/retrofe/src/default/Package/Environment/Common/layouts/Default%2016x9/layout.xml?at=default| An example of a layout.xml]]

The global settings.conf file contains the default layout used by RetroFE. It is however possible to give a collection a completely different layout by adding the layout.xml and layout artwork to the /layouts/<layout name>/collections/<collection name>/layout/ directory. A splash.xml is not required/used for a collection's layout. This way you can give each collection a completely different look and feel.

RetroFE will first search for a layout XML file that matches the screen ratio, so e.g. layout 16x9.xml or layout 4x3.xml. If that file is not found, it will default to layout.xml. 
\\
\\
===== General Layout Structure =====

A layout generally consists of the following structure:

<layout>
   <sound/>
   <menu/>
   <video/>
   <image/>
   <text/>
   <reloadableVideo/>
   <reloadableImage/>
   <reloadableText/>
   <reloadableScrollingText/>
  </layout>
\\
===== <layout> Parameters =====

The <layout> tag can use the following parameters:

|width| The virtual width to use for this layout. This will be scaled automatically by the frontend if the screen resolution is different.|
|height|The virtual height to use for this layout. This will be scaled automatically by the frontend if the screen resolution is different.|
|loadFontSize| The size (quality) of the font to load. Lower font sizes is more blurred, Higher font sizes are a little more pixelated. It is best to set this to the same value as fontSize most used in the layout.|
|font| Location of the font (relative to the layout folder).|
|fontColor| Default RGB color of the font (in hex, i.e. “6699AA”).|
|fontSize| Default font size of to display if not specified by a component.|
|minShowTime|Minimum amount of time (in seconds) to show the current layout (only applicable in splash.xml).|

Example:
  <layout width="1920" height="1080" font="Roboto-Bold.ttf" loadFontSize="64" fontColor="dedede">

\\
=====<sound> Parameters=====

The <sound> tag can use the following parameters:

<sound>tag parameters

^Tag ^Description^
|type|triggers on the following events: %%"%%load%%"%% %%(%%page load%%)%%, %%"%%unload%%"%% %%(%%page exit%%)%%, %%"%%highlight%%"%% %%(%%scroll%%)%%, %%"%%select%%"%% %%(%%entering game%%/%%sub-menu%%)%%.|
|src|Location of the sound file (relative to the layout folder).|

Example:

\\

=====<menu> Parameters=====

The <menu> tag is used to define a menu structure, and uses the following structure:

The <menu> tag supports the following parameters:

^<menu> tag parameters^^ 
|type 	|The type of menu to display. Set to custom to specify all the points on the screen. Set to vertical to have a vertical scrolling list prebuilt for the layout|
|imageType 	|If specified, uses an image to be displayed for each menu item (if it exists). Text will be used if the image could not be found.|
|orientation 	|Set to "horizontal" to use the Left/Right controls to scroll. set to "vertical" to use Up/Down.|
|scrollTime 	|The amount of time (in seconds) it takes for an item to scroll to the next point on the menu (i.e 0.750 = 750 milliseconds)|
|scrollAcceleration 	|The acceleration rate to scroll by when holding down the up/down/left/right scroll key|
|menuIndex      |The index at which the menu should be inserted in the menu hierarchy. If omitted, the menu will be inserted at the next index. This also allows multiple menus to be inserted at the same index, displaying multiple menus at the same time.|

\\
The <itemDefaults> tag supports the following parameters:

^<menu> <itemDefaults> tag parameters^^ 
|spacing |Used when the menu type is set to vertical. Defines the spacing in pixels for all edges of a menu item.|
|index |Used when the menu type is set to vertical. Specify a options for a particular menu item when in list mode (first=first visible item, last=last visible item, start=first - 1, end - last + 1)|
|font |Location of the font (relative to the layout folder).|
|fontColor |Default RGB color of the font (in hex, i.e. “6699AA”).|
|fontSize |Default font size of to display if not specified by a component.|
|loadFontSize|The size (quality) of the font to load. For the best results, use the same value as fontsize.|

\\
The <item> tag supports the following parameters:

For more information, see this [[https://bitbucket.org/teamretro/retrofe/src/default/Package/Environment/Common/layouts/Default%2016x9/layout.xml?at=default|example]] 
\\
\\
=====<image> Parameters=====

The <image> tag supports the following parameter:

^<image> tag parameters^^ 
|src 	|The location of the image to display (relative to the location of the active layout folder)|

Example:

\\
=====<text> Parameters=====

The <text> tag supports the following parameters:

Example:

<text value="Year:" x="300" y="850" xOrigin="right" yOrigin="top" fontSize="48" layer="7"/>
\\

=====<reloadableVideo> Parameters=====

The <reloadableVideo> tag can be used to display a video of the selected item, and supports the following parameters:

Example:

\\
=====<reloadableImage> Parameters=====

The <reloadableImage> tag can be used to display an image of the selected item, and supports the following parameters:

^<reloadableImage> tag parameters^^ 
|type 	|The type of image to display: “numberButtons”, “numberPlayers”, “ctrlType”, “numberJoyWays”, “rating”, “score”, “year”, “title”, “developer”, “manufacturer”, “genre”, “playlist”, “collectionName”, “collectionSize”, “collectionIndex”, “collectionIndexSize”, or any type you pick where the title will be used as the name of the file.|
|mode 	|See mode attribute for more details|
|textFallback 	|Set to true to have text displayed of a the item title if an image cannot be loaded|
|font 	|Location of the font (relative to the layout folder).|
|fontColor 	|Default RGB color of the font (in hex, i.e. “6699AA”).|
|fontSize 	|Default font size of to display if not specified by a component.|
|loadFontSize 	|The size (quality) of the font to load. For the best results, use the same value as fontsize.|

Example:

\\

=====<reloadableText> Parameters=====

The <reloadableText> tag can be used to display textual information about the selected item, and supports the following parameters:

^<reloadableText> tag parameters^^ 
|type 	|The type of text to display: "time", "numberButtons", "numberPlayers", "ctrlType", "numberJoyWays", "rating", "score", "year", "title", "developer", "manufacturer", "genre", "playlist", "collectionName", "collectionSize", "collectionIndex", or "collectionIndexSize".|
|mode 	|See mode attribute for more details|
|font 	|Location of the font (relative to the layout folder).|
|fontColor 	|Default RGB color of the font (in hex, i.e. “6699AA”).|
|fontSize 	|Default font size of to display if not specified by a component.|
|loadFontSize 	|The size (quality) of the font to load. For the best results, use the same value as fontsize.|

Example:

The type="time" allows for an additional parameter: timeFormat, which follows the C++ [[http://en.cppreference.com/w/cpp/chrono/c/strftime|strftime]] abilities.

\\
=====<reloadableScrollingText> Parameters=====

The <reloadableScrollingText> tag can be used to display textual information about the selected item, loaded from a text file, and supports the following parameters:

^<reloadableText> tag parameters^^ 
|type 	|The type of text file to load. Files are generally placed as <collection name>/medium_artwork/<type>/<game name>.txt or <collection name>/system_artwork/<type>.txt. In addition, the following meta fields are supported: “numberButtons”, “numberPlayers”, “ctrlType”, “numberJoyWays”, “rating”, “score”, “year”, “title”, “developer”, “manufacturer”, “genre”, “playlist”, “collectionName”, “collectionSize”, “collectionIndex”, or “collectionIndexSize”.|
|mode 	|See mode attribute for more details.|
|font 	|Location of the font (relative to the layout folder).|
|fontColor 	|Default RGB color of the font (in hex, i.e. “6699AA”).|
|fontSize 	|Default font size of to display if not specified by a component.|
|loadFontSize 	|The size (quality) of the font to load. For the best results, use the same value as fontsize.|
|direction 	|The direction in which the text should scroll: horizontal, vertical.|
|scrollingSpeed 	|The speed at which the text should scroll in pixels per second.|
|startPosition 	|The x/y offset of the start position of the text.|
|startTime 	|The delay before the text starts scrolling.|
|endTime 	|The delay between the finish of the scroll, and restarting the display of the text.|
|alignment 	|The text alignment for vertical scrolls: left, right, centered, justified.|

The text will scroll across the screen until it is no longer visible. Then it will be reset. For a vertical scroll: if the startPosition is 0, and the text fits within the defined size, the text will not scroll.

Example:

\\
=====General Parameters=====

The other tags all support a general set of parameters:

RetroFE supports 20 layers of images (0-19) to allow items to overlap in a controlled fashion.

Usage of the x/y/xOffset/yOffset/xOrigin/yOrigin parameters:

Usage of the xOffset/yOffset parameters is generally reserved for when you use values like "top|bottom|left|right|center" for x and/or y, e.g. x="center" xOffset="10" will place the object 10 pixels right of the center.

All these paremeters can also be used in animations to create an even more beautiful layout experience. These animations use the following syntax:

<action type>
    <set duration="<time in seconds>"
      <animate type="<animation parameter>" from="<from setting>" to="<to setting>" algorithm="<algorithm_setting>"/>
    </set>
  </on<action_type>

It is possible to put multiple animates in the same set; these animations will happen at the same time. It is possible to put multiple sets in the same action type: these animations will happen in sequence. It is possible to omit the from attribute; this will animate from the current value. It is possible to use type="nop" (no operation), without any other attributes (<animate type="nop"/>. This can e.g. be used to delay an animation by preceding it with a set containing just a "nop" animation.

RetroFE supports the following action types:

The action type can be combined with a menuIndex attribute. This will force RetroFE to only activate the animation for the specified menu index, with 0 being the main menu. Some examples:
^  menuIndex  ^  Activated on  ^
| menuIndex="0"  | Activate the animation on the main menu. |
| menuIndex="1"  | Activate the animation on first submenu. |
| menuIndex="%%!%%0" | Activate the animation on every index except for the main menu. |

Edit summary

RetroFE Documentation

User Tools

Site Tools

Page Tools