Variables
A variable is a string of text that is associated with a short, memorable name. Variable names can be used in most options throughout the skin, in place of the associated text.
Variables are helpful when a certain string is repeated many times throughout the skin. By referencing the variable name instead of the full string, the amount of "redundant" code is reduced, as is the overall size of the skin. Variables also simplify the task of changing values. A variable string can be modified in a single location, and without recreating the entire option in which it is used.
[Variables] section
Each skin may have a special section called [Variables]. Each option in [Variables] defines a variable name. Unlike most other option names in Rainmeter, variable names are not limited to a specific list. They can have any valid name, as long as they do not conflict with Rainmeter's built-in variables.
[Variables] |
Using Variables
Variable names are referenced in other options in one of two ways:
Normal variables syntax
#VarName#
Nested variables syntax
[#VarName]
[MeterMyVar1] |
Variables can also be used to define other variables:
[Variables] |
Changing Variables
The !SetVariable bang can be used to change variable values dynamically. !SetVariable can also be used to create a variable that does not already exist in the [Variables] section.
[!SetVariable "MyVar1" "This is a new string!"]
Alternatively, the !WriteKeyValue bang can be used to add or change values in [Variables]. The skin must be refreshed to apply changes made by !WriteKeyValue.
[!WriteKeyValue "Variables" "MyVar2" "New value"]
Dynamic Variables
A variable whose value changes while the skin is active is called a dynamic variable. Dynamic variables allow a skin to store, retrieve and display ever-changing information without refreshing the skin.
Dynamic variables can only be used in a measure or meter by setting the option DynamicVariables=1
.
Note that any [MeasureName]
used in a bang as a Section Variable is automatically dynamic, and DynamicVariables=1
is not required.
In addition, there are some [Sections] and plugins which do not support dynamic variables at this time. The following are sections where dynamic variables cannot be used:
- [Rainmeter]
- [Variables]
- [Metadata]
- iTunes
- MediaKey
- Power
- 3rd-party plugins are not guaranteed to support dynamic variables.
When a meter or measure has dynamic variables enabled, Rainmeter uses marginally more processor power. This difference is negligible for most skins, but it may be noticeable in very large, complex skins with many dynamic variables, or on image meters with very large images. For this reason, it is recommended to use dynamic variables only when necessary, and use alternatives such as !SetOption in other cases.
Built-In Variables
Rainmeter automatically creates a number of helpful variables for each skin. These variables do not need to be defined in the [Variables] section. Some built-in variables are dynamic.
For a complete list, see Built-In Variables.
Section Variables
Some measure and meter properties can also be referenced as dynamic variables by using the section name in brackets []
, as in [SectionName]
. These section variables can also be modified by certain parameters, as in [SectionName:P1,P2]
.
For more, see Section Variables.
Event Variables
Some action options allow the use of special variables that are related to the specific event that triggers the action. These variables are referenced by surrounding the name with dollar signs ($
), as in $Foo$
. Event variables are evaluated at the time the action is triggered, used to execute the action, and then immediately discarded. For example, when using a command with the InputText plugin, the event variable $UserInput$
refers to the string that was entered into a text input box by the user.
Environment Variables
Windows environment variables can be referenced as variables in Rainmeter by using the variable name contained between percent signs (%
), such as %APPDATA%
or %SystemDrive%
. To see a complete list of environment variables available on your system, open a Windows command prompt (cmd.exe) and type set
.
Escaping Variables
Rainmeter always attempts to replace #Name#
or [Name]
with a value, if "Name" refers to an existing variable, meter or measure. To prevent a variable reference from being replaced, escape the "Name" of the variable with asterisks (*
).
Normal variables
#*VarName*#
[*MeasureName*]
Nested variables
[#*VarName*]
[&*MeasureName*]
These are replaced with the literal strings without the *
, rather than the resolved values. The !SetOption bang can use these escape characters to protect variable references when setting options on dynamic meters or measures.