Variables

From ThrottleWiki

Throttlelauncher allows you to make use of variables. The synax of variables is #@VARNAME#. You can use the variables in many places, like parameters, iconpaths, texts, attributes. When TrottleLauncher is running, the variable is evaluated and #@VARNAME# is substituted with the result. There are three kinds of variables: user variables, system variables and constants

User variables need to be defined in the variables section of the config.xml. This makes them show up in the theme configurator and allows users to change behavior of the theme without editing the xml.
System variables allow information (text, images) to be shown depending on the system state or registry values. They are built-in and can be applied without defining them.
ThrottleLauncher contains a number of constants referring to localized filepaths. They are replaced with the actual path name in the localized version of WM of the device, allowing for themes to work in different WM versions without modification.

Defining user variables

You define a user variable by adding a variable element in the variables section of the config.xml as follows

<variables>
	<var name="VARNAME_1" description="VARDESCRIPTION_1" default="DEFAULTVALUE_1" type="VARTYPE_1" />
	<var name="VARNAME_2" description="VARDESCRIPTION_2" default="DEFAULTVALUE_2" type="VARTYPE_2" />
	....
	<var name="VARNAME_N" description="VARDESCRIPTION_N" default="DEFAULTVALUE_N" type="VARTYPE_N" />
<variables>

The several tag attributes are mandatory and mean the following:

name: is the name of the variable. This is the name when using the variable in your theme.
description: this is the user friendly description of the variable, which will show up in the configurator.
default: it's the default value of the variable that will be applied if no user customization is done.
type: defines the type of the variable. Depending of the variable type it will be displayed as diferent objects in the user customization dialog. Valid variable types are:
- separator: This is a dummy variable and must not be used on the theme. It is used to group variables on different tabs in the configurator. The name of the separator is the name of the tab. This type does not have a defaultvalue.
- string: will give the user a textbox so he can write the value of the variable on it.
- boolean: will show a combo with true/false options to the user.
- combo: must be specified as combo(option1,option2,...,optionN). Will display a user a combo with the specified options.
- decimal: must be specified as decimal(minvalue,maxvalue). Will display a trackbar so user can select a decimal value (2 decimal positions).
- integer: same as avobe but with integer numbers.
- orderlist: must be specified as orderlist(option1,option2,...,optionN). Will display a list with checkboxes and ordering arrows so the user can change the order or uncheck any of the options.
- path: specified as path(pattern_1,pattern_2,...,pattern_N). Will allow the user to select a file path or folder matching one of the specified patterns.
- todayplugin: will display a list with check boxes of all the today plugins that are currently unchecked on the Windows Mobile today plugins dialog. This is usefull in combination with the plugin tag that will be set later on.

When a theme is loaded and no vars.xml file is present, all variables are loaded with their default value. When the user changes the value of any variable using the configurator, a vars.xml is created in the setup folder with the new value(s), (and the default values of the unchanged ones). When throttle is reloaded and a vars.xml file is present, the values of that vars.xml file are taken.

Using variables

Variables can be used as the value of an attribute or parameter, so its value can be changed using the configurator instead of having to edit the setup xmls. Variables can also be used in an iconpath or text to change their value, but their most powerful usage is to use systemstate variables to change the displayed image or text on the basis of system state or registry values.

The syntax to obtain a registry value is as follows:

#$Registry,registry_path[,Operations[,OperationParams]]#

SystemState is the "source". Other valid sources you already know are:

#$SystemState,PROPERTY[,Operations[,OperationParams]]#

allowed values for PROPERTY are:

any of these
FreeMemoryPercent
UsedMemoryPercent
TotalMemorySize
FreeMemorySize
FreeDeviceStoragePercent
UsedDeviceStoragePercent
FreeDeviceStorageSize
TotalDeviceStorageSize
FreeStorageCardPercent
UsedStorageCardPercent
FreeStorageCardSize
TotalStorageCardSize

Allowed operations:

intervals,x: rounds the systemstate values to the nearest multiple of x
map, [actual_value-result_value|default-value_in_all_other_cases]: translates "actual_value" into "result_value" and all other values into "value_in_all_other_cases"
exists: will return true if the property has value, otherwise returns false.
bool: will return true if the property value is not 0.

Examples:

height="#@rowheight#"

Allows to define the rowheight from the configurator.

path="...\weather_#$Registry,HKEY_LOCAL_MACHINE\Software\ThrottleLauncher
\GoogleWeather\forecast1\condition#.png"

When used in an icon or text, this displays the appropriate icon for todays weather, e.g. "weather_rain.png", in combination with weather2reg

text="#$Registry,HKEY_LOCAL_MACHINE\Software\ThrottleLauncher\GoogleWeather\forecast2
\Day#:High=#$Registry,HKEY_LOCAL_MACHINE\Software\ThrottleLauncher\GoogleWeather\forecast2\High#°C"

This could become "Sun: High=34°C"

path="#@iconpath#\apps\#@iconset#\BT_#$SystemState,BluetoothStatePowerOn,map,[1-on|default-off]#.png"

when used in an icon or text element, this displays either the icon BT_on.png or BT_off.png depending on the bluetooth state

path="#@iconpath#\apps\#@iconset#\wifi_#$SystemState,WiFiStatePowerOn,map,[1-on|default-off]#.png"

Similar for wifi

path="...\#$SystemState,time,date,MM#_#$SystemState,time,date,dd#.png"

This can be used to display ical calender icons like "01_04.png"

HKLM\SYSTEN\state\voip\current\status

contains the connection status of your voip connection if you have any

ROM-Language independent constants

#$PROGRAMFILES#: ProgramFiles folder.
#$WINDOWS#: Windows folder
#$PROGRAMS#: /Windows/StartMenu/Programs
#$THEME_BASE#: The folder that contains your theme, e.g. \Program files\Throttlelauncher\setups\mytheme
#$GENERICROOT#. This is special as is used as root. What this alias will do is look inside "\" inside "\Storage Card" "\Bluetooth" and almost all removable media for the desired path.

example of this could be a path like: #$GENERICROOT##$PROGRAMFILES#ThrottleLauncher

Date

The date variable allows you to display or otherwise use the date or time with your own formatting. It is update every second.

Syntax: #$date,formatstring#

The formatstring can be (almost?) any string, and the result is exactly the same but with some specific combinations replaced by the actual value. Like:

HH: hours in 24 hr format [0-23]
hh: hours in 12 hr format [0-11]
mm: minutes [00-59]
ss: seconds [00-59]
tt: AM or PM
y: month, year (January, 2010)
yy: year in two digits (10)
yyyy:year in four digits (2010)
MM: month in two digits [01-12]
MMM: month in three letters [Jan-Dec]
MMMM: month fully written [January-December]
d: short date as specified in regional settings
dd: day in two digits [01-31]
ddd: day of week in three letters [Mon-Sun]
dddd: day of week fully written [Monday-Sunday]

This means you can build your own date time format with fixed texts or separators, so

     #@date,today is dddd, dd-MMMM - YYYY and the time is hh:mm:ss,tt#

could look like:

 today is thursday, 23-September - 2010 and the time is 11:08:34,PM

ThrottleApps

Menu