Binding theme elements with data is allowed using dynamic variables.
Dynamic variables are to be written {type:property} ( ex: {game:name} ).
They can be used in every theme element of types int/float/bool/string/path is bindable, except vector elements ( NORMALIZED_RECT & NORMALIZED_PAIR ).
They can't be use in "if" attributes which requires static theme variables.
You can also use dynamic variables in the "enabled" attribute in the storyboards animation element ( <animation enabled="{global:cheevos}" [...] /> ).
The Binding engine supports standard operators evaluation ( +, -, *, /, &&, ||, ! ) and also simple evaluation methods.
Be careful : Dynamic variables should not be confused with static variables. Static Variables use the $ sign ( ${variableName} ). Static variables are evaluated when the theme loads only.
system:
name string
fullName string
manufacturer string
theme string
releaseYear string
hardwareType string
command string
group string Name of the group
collection bool
subSystems int Number of susbystems (collections / groups)
total int Number of games / elements
played int
favorites int
hidden int
gamesPlayed int
mostPlayed int
gameTime string
lastPlayedDate string
image path
showManual bool
showSaveStates bool
showCheevos bool
showFlags bool
showFavorites bool
showParentFolder bool
hasKeyboardMapping bool
isCheevosSupported bool
isNetplaySupported bool
hasfilter bool
filter string
collection: The collection object is of type system, and has the same properties. It exists only when the view is in a collection and represent the current collection system. It can be tested with the expression : empty({collection:name})
game:
system system object of type system. Properties can be accessed using {game:system:propertyname}
name string Scrapped name of the game
rom string Filename
stem string Filename, without extension
path string Full path
favorite bool
hidden bool
kidGame bool
gunGame bool
wheelGame bool
cheevos bool
folder bool
placeholder bool True if it's a placeholder ( item when a system is empty )
playerCount int
hasManual bool
hasSaveState bool
hasKeyboardMapping bool
gametime int time played in seconds
desc string
image path
thumbnail path
video path
marquee path
fanart path
titleshot path
manual path
magazine path
map path
bezel path
cartridge path
boxart path
boxback path
wheel path
mix path
rating float
releasedate date
releaseyear string
developer string
publisher string
genre string
family string
arcadesystemname string
players string
playcount int
lastplayed date
crc32 string
md5 string
lang string
region string
cheevosHash string
cheevosId int
directory string
type string
stars string returns a string composed of rating stars
nameShort string name, before any parenthesis
nameExtra string name, after any parenthesis
global:
help bool
clock bool
architecture string
cheevos bool
cheevosUser string
netplay bool
netplay.username string
ip string
battery bool
batteryLevel int
screenWidth int
screenHeight int
screenRatio string
vertical bool
Evaluation is done with a basic evaluation engine. Expressions are standard expressions, supporting common operators ( +, -, *, ^, /, ==, !=, !, &&, ||, ... ) You can do maths, or combine strings.
The engine also supports methods and conditions. You can apply methods to every object to transform them. Methods can be called as global methods 'exists({game:path})' or as object methods '{game:path}.exists()'
File and paths methods :
------------------------
exists(path) bool checks if a path exists. ex: exists({game:marquee})
isdirectory(path) bool checks the path is a directory.
getextension(path) string get file extension ( lower )
filename(path) string extract filename from a path
stem(path) string extract the stem ( filename without extension ) from a path. ex : <path>"${themePath}/art/gamemedias/" + stem({game:rom}) +".png"</path>
directory(path) string extract the directory from a path
filesize(path) long gets the file size in bytes
filesizekb(path) long gets a string with file size, formatted with kilobytes
filesizemb(path) long gets a string with file size, formatted with megabytes
String methods :
----------------
empty(string) bool checks if a string is empty.
upper(string) string makes a string uppercase
lower(string) string makes a string lowercase ex : lower(translate({game:cheevos} ? "YES" : "NO"))
trim(string) string trims spaces at begin and end of a string
proper(string) string make the first char uppercase, then lowercase.
tointeger(string) int converts a string to an integer ( for evaluation purpose )
toboolean(string) bool parse a string and convert to boolean value
translate(string) string translate an english string to current locale. The source string must exist in the resources\locale po/mo files. ex : translate("never"), translate("Unknown"), translate("YES"), translate("NO")
contains(string, string) bool
startswith(string, string) bool
endswith(string, string) bool
default(string) string default text for empty values. "None" when a value is 0 or false. "Unknown" when the value is empty
Math :
------
min(int, int) int
max(int, int) int
clamp(int, int, int) int
tostring(int) string converts an integer to a string ( for evaluation purpose )
Date methods :
--------------
elapsed(date) string converts a date to a duration from now, to a string "8 days ago". ex : empty({game:lastplayed}) ? translate("never") : elapsed({game:lastplayed})
expandseconds(int) string formats a duration in seconds, to a string "3 hours ago". ex : {game:gametime} == 0 ? translate("Unknown") : expandseconds({game:gametime})
formatseconds(int) string formats a duration in seconds, to a string with format "03:10" ex : {game:gametime} == 0 ? "00:00" : formatseconds({game:gametime})
year(date) string extract the year of a date to a string
month(date) string extract the month of a date to a string
day(date) string extract the day of a date to a string
Conditions :
------------
X ? A : B condition
Static variables are evaluated when the theme loads. Values can't change at runtime. They are documented in THEMES.md
They can be used in every element or condition, and custom static variables can be created in the element. They are used with the syntax ${XXX} ( ex : ${global.clock} )
global.architecture
global.help bool
global.clock bool
global.cheevos bool
global.cheevos.username string
global.netplay bool
global.netplay.username string
global.language string
screen.width float
screen.height float
screen.ratio string
screen.vertical bool
system.cheevos bool
system.netplay bool
system.savestates bool
system.fullName string
system.group string
system.hardwareType string
system.manufacturer string
system.name string
system.releaseYear string
system.releaseYearOrNull string
system.sortedBy string
system.theme string
system.command string
themePath string root folder of the theme (not ending with /).
currentPath string folder of current theme xml file (not ending with /)
Show image only if the game image exists :
<image>
<visible>exists({game:image})</visible>
...
Show image in color if it's a favorite, in gray if it's not :
<image>
<saturation>{game:favorite} ? 1 : 0</saturation>
Display the current system name ( can be collection or group ) :
<text>
<text>{system:name}</text>
Display the game's system name :
<text>
<text>{game:system:name}</text>
Enable a storyboard animation only if the game has a video :
<storyboard>
<animation enabled="exists({game:video})" property="opacity" from="0" to="1" duration="400"/>
Load an image for a game, based on the rom name :
<image>
<path>"${themePath}/art/gamemedias/" + stem({game:rom}) +".png"</path>