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.
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] Foo=This is a string! Bar=So is this!
Variable names are referenced in other options by surrounding the name with pound signs (
#), as in
#Foo#. When the skin is loaded, Rainmeter replaces the variable reference with the corresponding string. Variables are inserted "literally," which means they can be mixed with other variables or regular text.
[MeterFoo] Meter=String Text=The value of my "Foo" variable is: #Foo# FontColor=#Red#,#Green#,#Blue#,#Alpha# [MeterBar] Meter=String Text=The value of my "Bar" variable is: #Bar# FontColor=#Red#,#Green#,#Blue#,#Alpha#
Variables can also be used to define other variables:
[Variables] Foo=rainmeter Bar=http://www.#Foo#.net/
!WriteKeyValue "Variables" "Foo" "This is a new string!"
!SetVariable "Foo" "This is a new string!"
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 with the option
[MeasureName] used in a bang as a Section Variable is automatically dynamic, and
DynamicVariables=1 is not required.
In addition, there are some plugins which do not support dynamic variables at this time. The following are sections where dynamic variables cannot be used:
- 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.
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.
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
For more, see Section 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.
Windows environment variables can be referenced as variables in Rainmeter by using the variable name contained between percent signs (
%), such as
%SystemDrive%. To see a complete list of environment variables available on your system, open a Windows command prompt (cmd.exe) and type
Rainmeter always attempts to replace
[Name] with a value, if "Name" refers to an existing variable, meter or measure. To prevent a variable reference from being replaced, place asterisks (
*) inside the containers, as in:
These are replaced with the literal strings
[Bar] respectively. The !SetOption bang can use these escape characters to protect variable references when setting options on dynamic meters or measures.