funkey/RetroFE
1
0
Fork 0
mirror of https://github.com/FunKey-Project/RetroFE.git synced 2025-12-12 17:58:53 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity
RetroFE/Documentation/Manual/Layouts.rst
emb 1a82ea34a2 Updating to support new layout tags
2015-01-13 12:55:06 -06:00

634 lines
32 KiB
ReStructuredText
Raw Permalink Blame History

.. _Layouts:
**********
Layouts
**********
A layout defines your user experience for displaying a collection. The layout XML file defines where graphical components are displayed, what audio is played, and how to animate components when certain events occur.
Each collection can have its own layout. Edit your :ref:`ConfigurationCollections` files to pick your layout.
File format
####################
All XML tags must be inside the root layout tag.
.. code-block:: xml
<layout>
...
</layout>
<layout> attributes
===================
=========================== =====================================================================================================================================
Attribute Description
=========================== =====================================================================================================================================
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.
font Location of the font (relative to the layout folder). TTF is only supported.
fontColor RGB color of the font (in hex, i.e. "336699")
loadFontSize The size of the font to load. Lower font sizes is more blurred, Higher font sizes are a little more pixelated. 24 is an ideal value.
=========================== =====================================================================================================================================
The following example uses a layout that is setup for 1024x768 pixels (4:3 aspect ratio). The frontend will handle layout scaling if your monitor runs at a larger resolution
and is of the same aspect ratio (i.e 1600x1200). The frontend will still handle layout scaling if the aspect ratio is different, however, your image will look stretched
(i.e 1920x1080 resolution, 16:9 aspect ratio).
.. code-block:: xml
<layout width="1024" height="768">
...
</layout>
The following example sets the menu font to Age.otf with a color of Royal Blue Red=41(65) Green=69(105) Blue=E1(225)
.. code-block:: xml
<layout width="1024" height="768" font="Age.otf" fontColor="FF6633">
<!-- menu items go inside here -->
</layout>
Components
##########
A component is a graphical item to be displayed on your screen (i.e. a menu, image, video, text).
=========================== ===========================================================================
Top Level Components Description
=========================== ===========================================================================
<menu> Menu for layout (can only contain one menu per layout)
<container> An empty container block (typically used for creating colored blocks)
<image> Display a single image (i.e. a background image)
<reloadableImage> An image that is reloaded with one for a particular selected item
<reloadableVideo> Display a video for the selected item
<reloadableText> Display text for the selected item
<text> Display custom text
=========================== ===========================================================================
Component attributes
====================
Each component (listed above) supports the following attributes:
=========================== ================================================================================
Attribute Description
=========================== ================================================================================
x X coordinate of where to place the component
y Y coordinate of where to place the component
xOffset Relative X offset of how many pixels to shift the object from x (x + xOffset)
yOffset Relative Y offset of how many pixels to shift the object from y (y + yOffset)
xOrigin X offset on image to use as the pin point for placement
yOrigin Y offset on image to use as the pin point for placement
alpha 0 = 0% visible, 0.5=50% visible, 1=100% visible
angle Angle to rotate image, in degrees
width Width of the component. Image will be scaled appropriately if not specified.
height Height of the component. Image will be scaled appropriately if not specified.
minWidth Minimum width to allow the image to be (if scaling is needed)
minHeight Minimum height to allow the image to be (if scaling is needed)
maxWidth Maximum width to allow the image to be (if scaling is needed)
maxHeight Maximum height to allow the image to be (if scaling is needed)
fontSize Size of font to display component is rendering text
backgroundColor Fill the component with a background color
backgroundAalpha Background color transparency: 0 = 0% visible, 0.5=50% visible, 1=100% visible
=========================== ================================================================================
(As a reminder, all examples shown below must be inside a <layout> tag)
Relative Positioning Diagram
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: coordinates.png
:width: 400pt
Attribute values (alignment)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Keywords can be passed into the values of some attributes for alignment.
All horizontal based attributes (i.e. x, xOffset, xOrigin, width, minWidth, maxWidth) can support the following values: "left", "center", "right", "stretch"
All vertical based attributes (i.e. x, yOffset, yOrigin, height, minHeight, maxHeight) can support the following values: "top", "center", "bottom", "stretch"
Display an image stretched across the the screen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: xml
<image x="0" y="0" width="stretch" height="stretch" source="background.png"/>
Display an image centered on the screen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: xml
<image x="center" y="center" xOrigin="center" yOrigin="center" width="200" height="300" />
Display an image aligned at the bottom right of the screen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use the bottom rightmost pixel as the reference point when displaying on the screen and display at the bottom rightmost position.
.. code-block:: xml
<image x="right" y="bottom" xOrigin="right" yOrigin="bottom" width="200" height="300" />
Display an image being offset 100 pixels from the right of the page (vertically centered)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use the rightmost (vertical center) pixel as a reference point when displaying on the screen.
Display at the right-center area of the page.
Offset the image to the left by 100 pixels.
.. code-block:: xml
<image x="right" y="center" xOrigin="right" yOrigin="center" xOffset="-100" yOffset="0" width="300" height="300" />
Animations
###########
The animation engine is very flexible. You can move, rotate, scale, and make images transparent. See the basic example XML for performing an animation. The sections below explain what each tag is responsible for.
.. code-block:: xml
<!-- Move an image from the top left to the center of the screen for 1 second.
Then move the image from the center of the screen to the bottom of the screen in 0.5 seconds -->
<image xOrigin="center" yOrigin="bottom" width="200" height="300">
<onEnter>
<set duration="1">
<animation type="x" from="0" to="center" algorithm="linear">
<animation type="y" from="0" to="center" algorithm="linear">
</set>
<set duration="0.5">
<animation type="y" from="center" to="bottom" algorithm="linear">
</set>
</onEnter>
</image>
===================================== =================================================================================================
Tag (in example above) Description
===================================== =================================================================================================
<image> The component to animate. In this case it is an image.
<onEnter> When to trigger the event. In this case it will be triggered when the page is first loaded.
<set> Groups component properties to animate. In this case the first group animates the x and y coordinates
together for one second and then later animates the y axis for half a second.
<animation> Defines the start, end, and algorithm to use for animating a property (in this case the X and Y position).
<onIdle> Event that is continuously looped when there is no active input (when the menu is idling)
===================================== =================================================================================================
Events
===================
The following animations are supported by all component tags.
===================================== =================================================================================================
Tag Description
===================================== =================================================================================================
<onEnter> Events that are triggered when the layout first starts
<onExit> Events that are triggered when the layout exits
<onHighlightExit> Events that are triggered when the currently highlighted item is no longer highlighted
<onHighlightEnter> Events that are triggered when the item is highlighted
<onIdle> Event that is continuously looped when there is no active input (when the menu is idling)
===================================== =================================================================================================
.. code-block:: xml
<image xOrigin="center" yOrigin="bottom" width="200" height="300">
<onEnter>
<!-- add animation sets here for when you first enter the page -->
</onEnter>
<onExit>
<!-- add animation sets here for when you exit the page -->
</onExit>
<onHighlightEnter>
<!-- add animation sets here to run when a new item is highlighted -->
</onHighlightEnter>
<onHighlightExit>
<!-- add animations here for when a new item in the menu is highlighted
(how to animate the previously selected item) -->
</onHighlightExit>
<image>
<set> animation tag
===================
An animation <set> is a collection of animation properties to change at the same time. You can "daisy chain" multiple animations.
.. code-block:: xml
<image>
<onIdle>
<set duration="1">
<!-- animate certain properties for one second -->
</set>
<set duration="0.5">
<!-- animate certain properties for 0.5 seconds after the last animation set has completed -->
</set>
</onIdle>
<image>
<animation> tag
===============
An animation tag defines what property to animate.
=========================== ==================================================================================================================================
Attribute Description
=========================== ==================================================================================================================================
type Component property to animate. Supported types are: x, y, width, height, transparency, angle, xOrigin, yOrigin, xOffset, yOffset
from Starting value
to Ending value
algorithm Motion (tweening) algorithm. Defaults to linear if not specified. See Animation algorithms for more information.
=========================== ==================================================================================================================================
The following example animates an image on the x axis to move from the left to the right of the screen in 1 second.
.. code-block:: xml
<image xOrigin="center" yOrigin="bottom" width="200" height="300">
<onIdle>
<set duration="1">
<animation type="x" from="left" to="right" algorithm="linear">
</set>
</onIdle>
</image>
The following example animates an image on the x axis to move from the top left to the bottom right of the screen in 1 second.
.. code-block:: xml
<image xOrigin="center" yOrigin="bottom" width="200" height="300">
<onIdle>
<set duration="1">
<animation type="x" from="left" to="right" algorithm="linear">
<animation type="y" from="top" to="bottom" algorithm="linear">
</set>
</onIdle>
</image>
Animation algorithms
^^^^^^^^^^^^^^^^^^^^^
See http://gizma.com/easing/ for examples on how each animation operates.
===================================== =================================================================================================
Algorithm Description
===================================== =================================================================================================
linear no easing, no acceleration (default if none is specified)
easeinquadratic accelerating from zero velocity
easeoutquadratic deaccelerating from zero velocity
easeinoutquadratic acceleration until halfway, then deceleration
easeincubic accelerating from zero velocity
easeoutcubic deaccelerating from zero velocity
easeinoutcubic acceleration until halfway, then deceleration
easeinquartic accelerating from zero velocity
easeoutquartic deaccelerating from zero velocity
easeinoutquartic acceleration until halfway, then deceleration
easeinquintic accelerating from zero velocity
easeoutquintic deaccelerating from zero velocity
easeinoutquintic acceleration until halfway, then deceleration
easeinsinusoidal accelerating from zero velocity
easeoutsinusoidal deaccelerating from zero velocity
easeinoutsinusoidal acceleration until halfway, then deceleration
easeinexponential accelerating from zero velocity
easeoutexponential deaccelerating from zero velocity
easeinoutexponential acceleration until halfway, then deceleration
easeincircular accelerating from zero velocity
easeoutcircular deaccelerating from zero velocity
easeinoutcircular acceleration until halfway, then deceleration
===================================== =================================================================================================
Daisy chained animation example
================================
Take an image and move it from the top left of the screen to the center in 1 second. After the animation completes move the image
from the center of the screen to the bottom center of the screen in 0.5 seconds.
.. code-block:: xml
<image xOrigin="center" yOrigin="bottom" width="200" height="300">
<onEnter>
<set duration="1">
<animation type="x" from="0" to="center" algorithm="linear">
<animation type="y" from="0" to="center" algorithm="linear">
</set>
<set duration="0.5">
<animation type="y" from="center" to="bottom" algorithm="linear">
</set>
</onEnter>
</image>
Fully animating
================================
While this example may not be practical; it showcases all the properties that can be animated.
.. code-block:: xml
<image xOrigin="center" yOrigin="bottom" width="200" height="300">
<onIdle>
<set duration="1">
<animation type="x" from="left" to="right" algorithm="linear">
<animation type="y" from="top" to="bottom" algorithm="linear">
<animation type="xOffset" from="left" to="right" algorithm="linear">
<animation type="yOffset" from="0" to="20" algorithm="linear">
<animation type="xOrigin" from="0" to="30" algorithm="easeinoutquintic">
<animation type="yOrigin" from="0" to="20" algorithm="linear">
<animation type="transparency" from="0" to="1" algorithm="easeinoutquintic">
<animation type="angle" from="0" to="360" algorithm="linear">
<animation type="height" from="0" to="300" algorithm="easeinoutquadratic">
<animation type="width" from="0" to="180" algorithm="easeincircular">
</set>
<set duration="0.5">
<animation type="x" from="right" to="left" algorithm="linear">
<animation type="y" from="bottom" to="top" algorithm="linear">
<animation type="xOffset" from="right" to="left" algorithm="linear">
<animation type="yOffset" from="20" to="0" algorithm="linear">
<animation type="xOrigin" from="30" to="0" algorithm="easeinoutquintic">
<animation type="yOrigin" from="20" to="0" algorithm="linear">
<animation type="transparency" from="1" to="0" algorithm="easeinoutquintic">
<animation type="angle" from="360" to="0" algorithm="linear">
<animation type="height" from="300" to="0" algorithm="easeinoutquadratic">
<animation type="width" from="180" to="0" algorithm="easeincircular">
</set>
</onIdle>
</image>
Images
####################
Component attributes
====================
See below for a list of supported attributes (in addition to the standard component attributes listed above)
=========================== ================================================================================
Attribute Description
=========================== ================================================================================
src location of the source image (relative to the layout folder)
=========================== ================================================================================
For example, if you want to display picture of an Nintendo console (named "NES Console.png" in your layout folder), you would do the following:
.. code-block:: xml
<image src="NES Console.png" x="center" y="center" height="200" />
Reloadable Images
##############################
Displays image for the currently highlighted menu item.
Component attributes
====================
See below for a list of supported attributes (in addition to the standard component attributes listed above).
=========================== =====================================================================================================================================================================
Attribute Description
=========================== =====================================================================================================================================================================
type Type of image to display (using the selected item).
=========================== =====================================================================================================================================================================
For example, if you want to display a snap shot of the selected menu item, you would do the following in your Layout.xml file:
.. code-block:: xml
<reloadableImage type="snap" x="center" y="center" height="200" />
Your Settings.conf file will have the following line
.. code-block:: xml
media.snap = D:/Video Game Artwork/Nintendo/Snaps
If an item titled "Tetris (USA)" was selected, the reloadable image component will try to load "D:/Video Game Artwork/Nintendo/Snaps/Tetris (USA).png". If no image could be found than nothing
will be displayed.
Reloadable Videos
##############################
Displays video for the currently highlighted menu item.
Component attributes
====================
See below for a list of supported attributes (in addition to the standard component attributes listed above).
=========================== =====================================================================================================================================================================
Attribute Description
=========================== =====================================================================================================================================================================
imageType Type of image to display if the video could not be found (using the selected item).
=========================== =====================================================================================================================================================================
For example, if you want to display a video of the selected menu item, you would do the following in your Layout.xml file:
.. code-block:: xml
<reloadableVideo x="center" y="center" height="200" />
Your Settings.conf file will have the following line
.. code-block:: xml
media.video = D:/Video Game Artwork/Nintendo/Videos
If an item titled "Tetris (USA)" was selected, the reloadable image component will try to load "D:/Video Game Artwork/Nintendo/Videos/Tetris (USA).png". If no image could be found than nothing
will be displayed.
If you do not want to display an image component if the video does not exist, simply do not specify an imageType attribute:
.. code-block:: xml
<reloadableVideo x="center" y="center" height="200" />
Reloadable Text
##############################
Displays textual info for the currently selected item
Component attributes
====================
See below for a list of supported attributes (in addition to the standard component attributes listed above).
=========================== =====================================================================================================================================================================
Attribute Description
=========================== =====================================================================================================================================================================
type Valid values are: numberButtons, numberPlayers, year, title, manufacturer
=========================== =====================================================================================================================================================================
Example to display the manufacturer and title for the selected game
.. code-block:: xml
<reloadableText type="manufacturer" x="0" y="0" fontSize="20" height="30"/>
<reloadableText type="title" 0="0" y="60" fontSize="20" height="30"/>
Rendering Text
##############################
Displays static text on the screen
Component attributes
====================
See below for a list of supported attributes (in addition to the standard component attributes listed above).
=========================== =====================================================================================================================================================================
Attribute Description
=========================== =====================================================================================================================================================================
value Contents of the text to display
=========================== =====================================================================================================================================================================
For example, if you want to display a video of the selected menu item, you would do the following in your Layout.xml file:
.. code-block:: xml
<text value="RetroFE rocks!" x="center" y="center" height="200" />
Menu
###########
The menu supports animations just like every other component. There can be only one menu per layout.
Component attributes
====================
See below for a list of supported attributes (in addition to the standard component attributes listed above).
=========================== =====================================================================================================================================================================
Attribute Description
=========================== =====================================================================================================================================================================
type set to "custom" if you desire to pick individual points (absolute points). Use this mode when doing a showcase, wheel, etc...
=========================== =====================================================================================================================================================================
menu <itemDefaults> tag
=========================
Specifies the default values for each item.
<menu orientation="horizontal" algorithm="easeincircular" xOffset="500" y="10" width="center" height="1040" speed="0.05" acceleration="0.05">
menu <itemDefaults> tag
===============================
Item defaults define the normal properties of each menu item on a page. All component attributes can be used in here along with the following attributes:
=========================== =====================================================================================================================================================================
Attribute Description
=========================== =====================================================================================================================================================================
spacing Pixel spacing between each menu item (ignored when using the menu in custom mode)
index 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)
=========================== =====================================================================================================================================================================
menu <item> tag in custom mode
===============================
Each menu <item> tag represents a point on where to display a scrolling list item in the menu. When scrolling, the items themselves will scroll/move from one item point to another.
If an attribute in <item> is not specified, it will use the attribute specified in the <itemDefaults> tag.
.. code-block:: xml
<menu type="custom">
<itemDefaults x="center" y="20" fontColor="FFCC00" layer="3"/>
<item xOrigin="center" yOrigin="20" />
<item xOrigin="center" yOrigin="40" />
<item xOrigin="center" yOrigin="60" />
<item xOrigin="center" yOrigin="80" />
<item xOrigin="center" yOrigin="100" />
<item xOrigin="center" yOrigin="120" />
</menu>
menu <item> tag in list mode (default)
=========================================
Each menu <item> tag represents an offset relative to the predefined menu x,y location. When scrolling, the items themselves will scroll/move from one item point to another.
If an attribute in <item> is not specified, it will use the attribute specified in the <itemDefaults> tag.
.. code-block:: xml
<menu orientation="horizontal" algorithm="easeincircular" xOffset="500" y="10" width="center" height="1040" speed="0.05" acceleration="0.05">
<itemDefaults spacing="10" x="center" height="35" fontSize="35" alpha="0.5" xOffset="20" yOrigin="center" layer="3"/>
<item index="start" height="0" spacing="0" alpha="0"/>
<item index="2" spacing="0" height="60" fontSize="60" alpha="1" selected="true"/>
<item index="end" height="0" spacing="0" alpha="0"/>
</menu>
Animating the menu and list items
==================================
Not only can the entire menu have an animation performed, the menu item at a particular point can also be animated. See below:
.. code-block:: xml
<menu x="center" y="20" fontColor="FFCC00">
<!-- have the entire menu jiggle to the left and the right -->
<onIdle>
<set duration="0.5">
<animation type="xOffset" from="0" to="-10">
</set>
<set duration="0.5">
<animation type="xOffset" from="-10" to="0">
</set>
</onIdle>
<item xOrigin="center" yOrigin="20" />
<item xOrigin="center" yOrigin="40" />
<item xOrigin="center" yOrigin="60" selected="true">
<!-- have this single menu item jiggle up and down -->
<onIdle>
<set duration="0.5">
<animation type="yOffset" from="0" to="-10">
</set>
<set duration="0.5">
<animation type="yOffset" from="-10" to="0">
</set>
</onIdle>
</item>
<item xOrigin="center" yOrigin="80" />
<item xOrigin="center" yOrigin="100" />
<item xOrigin="center" yOrigin="120" />
</menu>
Sounds
#######
In addition to displaying graphical components, the frontend supports sound effects that are triggered when certain events occur.
=============================== =================================================================================================
Tag Description
=============================== =================================================================================================
<onLoad> Sound triggered when the layout is started
<onUnload> Sound triggered when the layout is exited
<highlight> Sound triggered when a new item is highlighted. This will not loop while actively scrolling.
<select> Sound triggered when an item is selected2
=============================== =================================================================================================
Each sound effect supports the following parameters:
=========================== =====================================================================================================================================================================
Attribute Description
=========================== =====================================================================================================================================================================
src Location of the sound file (relative to the layout folder).
=========================== =====================================================================================================================================================================
.. code-block:: xml
<onLoad src="load.wav" /">
<onLoad src="unload.wav" /">
<onLoad src="highlight.wav" /">
<onLoad src="select.wav" /">
Reference in New Issue View Git Blame Copy Permalink