Manual

Documentation for the latest release version of Rainmeter. Use links in the sidebar to navigate.

Installation

Download the latest release or beta version from http://rainmeter.net. The installer (.exe) allows you to install both 'standard' and 'portable' installations.

Both 32bit and 64bit installations are done with the same installer.

If you are running on a 64bit version of Windows, you will be asked if you wish to install 64bit or 32bit Rainmeter. If the installer detects a previous version of Rainmeter on your system, the same architecture version will automatically be installed. If you wish to change from 32bit to 64bit, you should uninstall Rainmeter first.

Rainmeter will detect if you require either the C++ runtime libraries or the .NET libraries. The C++ runtimes are required to use Rainmeter. Chances are you already have them, but if not, Rainmeter will download and install them. The .NET libraries are required to use any of the C# plugins which come with Rainmeter. If you are running on Windows XP you will need at least Windows XP Service Pack 2 to install the .NET libraries. If you elect not to install the .NET files, you will not be able to use any plugins written in C#.

Rainmeter is fully compatible with Windows XP, Vista, and Windows 7.

The file which Rainmeter uses to keep track of the skins you have loaded and how they are configured (Rainmeter.ini) is stored in your "Application Data" folder, and all Rainmeter "skins" are stored in your "My Documents" folder.

Normal Installation

Run the installer. By default Rainmeter will install in "C:\Program Files\Rainmeter", but you may install it in any folder you wish. The installer presents you with a set of options allowing you to create Start Menu and desktop shortcuts, have Rainmeter automatically start with Windows, and install Rainmeter for all users.

When Rainmeter starts the first time, it will install the default skins and themes in the proper folder locations and load the illustro suite of skins.

Portable Installation

If you wish to run Rainmeter from one folder, so it can be easily taken with you or even run directly from a removable drive, all you need to do is download the latest installer and select 'Portable Install' during the install process. You will be prompted to browse for a location (for which you have full read and write access) to install Portable Rainmeter. After the install, you may use the program normally, but can easily take the application "on the road" by copying the entire \Rainmeter folder and sub-folders. Note that if you do a portable install, you are responsible for ensuring you have the appropriate C++ and .NET runtime libraries installed on your system.

Silent Installation (advanced)

Rainmeter can be installed silently (i.e. without user interaction) starting from version 2.1 beta. This is useful, for example, when deploying Rainmeter during the initial Windows setup. View switches and return values.

Default File Locations

Program files:
Windows XP: C:\Program Files\Rainmeter
Windows Vista and later: C:\Program Files\Rainmeter

Skins:
Windows XP: C:\Documents and Settings\YourName\My Documents\Rainmeter\Skins
Windows Vista and later: C:\Users\YourName\My Documents\Rainmeter\Skins

Rainmeter.ini and themes:
Windows XP: C:\Documents and Settings\YourName\Application Data\Rainmeter
Windows Vista and later: C:\Users\YourName\Appdata\Roaming\Rainmeter

Uninstalling

If you installed Rainmeter with the installer you can uninstall it from "Add or Remove Programs". If you installed Portable Rainmeter, just delete the folder you browsed for during the install process.

Ensure that Rainmeter is not running when uninstalling.

Settings

There is no fancy settings editor, so you need to change the settings with your favorite text editor. The general configuration settings are in a file named Rainmeter.ini. The skin settings are in the skin's respective .ini files.

Rainmeter.ini is in the following location:
Windows XP: C:\Documents and Settings\YourName\Application Data\Rainmeter
Windows Vista and later: C:\Users\YourName\Appdata\Roaming\Rainmeter

The file can be edited by using "Edit Settings" from the Rainmeter context menu or Manager.

The Rainmeter.ini file has several sections: [Rainmeter], [TrayMeasure], and individual sections for each config which has been loaded. The Rainmeter section contains general settings that can be used to change how Rainmeter behaves. The settings are used as default values for all new configs that are opened. Once a config is opened it will write the settings under its own section in the Rainmeter.ini file.

Important: Some of the settings in the Rainmeter.ini file cannot be changed while Rainmeter is running becase a refresh will write the old values back to the ini file. If you cannot change something, try changing the value after completely closing Rainmeter.

Settings-Rainmeter

The [Rainmeter] section of Rainmeter.ini defines general Rainmeter settings. The following must be put under the [Rainmeter] section:

Options

Settings-TrayMeasure

One special section is [TrayMeasure], which can be used to define a measure for the tray icon. You can use any measure for this as long as it returns some meaningful values (i.e. numbers between some limits). The following must be put under the [TrayMeasure] section:

Options

Settings-ConfigName

The following should be put under the the sections for their respective configs, e.g. [illustro\Clock]. Most of these settings can also be set via the skin right-click context menu or through the Manage dialog.

Options

Settings-BuiltInVariables

The following are pre-existing variables that are set and controlled by Rainmeter (i.e. their value cannot be manually changed). These variables may be used anywhere, including within Rainmeter.ini.

Note: Built-in Rainmeter variables that stand for a path already contain a trailing slash.

The variables below are dynamic in nature. As a result, DynamicVariables=1 must be set on the measure or meter in which they are used (note that they cannot be used elsewhere like under the [Rainmeter] section):

You may also use Windows environment variables, which can be obtained by the set command in cmd.exe (command prompt). To use them, use the name of the environment variable within two percent sign (e.g. %APPDATA%). Note that environment variables may vary from system to system.

Settings-Groups

Configs can be categorized into "groups" to allow quick control of multiple configs at once. To add a Config to a group, simply add the Group statement to the section under Rainmeter.ini. Alternatively, you may add Group under the [Rainmeter] section of the skin file.

Any number of groups may be added to a section, all of which must be separated by a vertical bar (i.e. "|"). Groups may also be specified under the [Rainmeter] section of Rainmeter.ini. In this case, that group will be considered the default for all configs that have no groups defined.

Example (Rainmeter.ini):

[Enigma\Sidebar\Systems]
Active=0
WindowX=0
WindowY=0
AlphaValue=255
FadeDuration=250
ClickThrough=0
SavePosition=1
SnapEdges=1
KeepOnScreen=1
Group=Enigma | Systems
The Enigma\Sidebar\Systems config be added to the "Enigma" and "Systems" groups, which can then be controlled through several bangs.

Example (skin):

[Rainmeter]
Update=1000
Author=Me
Group=Enigma | Systems
The skin is added to the "Enigma" and "Systems" groups, which can then be controlled through several bangs.

Settings-Monitors

There is a "Display Monitor" submenu in [Skins Menu]-[Position] of the Rainmeter tray icon.

These menus set the position of the skin to the desired monitor in a multiple monitor configuration.

AutoSelectScreen
If set to 1, the WindowX and WindowY "@n" settings are made automatically based on the position of the meter's window. If a monitor is selected directly using "Display Monitor" in the Rainmeter / skin context menu, this setting is reset to 0.

Built-in variables for multiple monitors

Variables for the virtual screen: Variables for the PRESENT monitor:
Note that these variables automatically change by the WindowX and WindowY "@n" settings. If "@n" is not set, these variables return the value of the primary monitor. Variables for the PRIMARY monitor: Variables for the SPECIFIED monitor (@1, @2, ...):

Skins

All skins are placed in the skin folder. Each skin must be in its own subfolder. The actual skin file is a normal .ini file with several sections that define the skin layout and values. A subfolder may contain several .ini files, but only one .ini file per folder can be active. This allows you, for example, to supply localized skins or different variations of some skin.

The skin's ini file is divided into several parts. All the general settings are put under the [Rainmeter] section, details about the are placed in the [Metadata] section, and the variables in the [Variables] section. Then follow the measures (which collect data) and meters (which display data). While it is not necessary to place the sections in this order, it is the convention that is observed by the vast majority of skin authors.

Note: While you can put sections in any order you wish, it is important to understand that Rainmeter reads and executes measures and meters in the order they are in the skin .ini file. This is important in particular for positioning of meters relative to each other.

Skins-Rainmeter

The [Rainmeter] section of a skin defines skin-wide options.

Background Options

Other Options

Skins-Metadata

This section contains information about the skin itself. Alone, metadata is useful as a consistent and reliable place to learn about a skin, and how it is meant to be used and configured. Metadata is also displayed in the Manage dialog.

It is important for all metadata to be written in the [Metadata] section using a specific set of keys. As a skin developer, you should provide appropriate values for all of these keys.

Options

Skins-Variables

The variables are keywords that are replaced in other settings. These can be used, e.g., to gather user defined values to the top of the config-file so that they can be easily changed. To define a variable, you must set a value for it in the [Variables] section of a skin or @Include file. To use a variable in a meter or measure, just surround the keyword with # characters.

Variables are defined as follows under the [Variables] section:
VariableName=Value

The variable can then be referred in measures and meters as:
#VariableName#

So to set a variable for the size of the font you want to use on all your meters you might use:

[Variables]
Size=11

[SomeMeter]
FontSize=#Size#

[SomeMeter2]
FontSize=#Size#

You can also tell Rainmeter to use the literal text of the keyword by adding asterisks inside the tag, as follows:
#*VariableName*#
This can be used e.g. in a bang to set the text of a String meter. Instead of only using the value of the variable at the time of the bang, this will send the keyword itself, and the receiving meter will update accordingly.

Note: There are several pre-defined variables you can use anywhere in Rainmeter.

Skins-AeroBlur

Allows users on Windows Vista or Windows 7 to enable "Aero" blur effects on skins. The Windows desktop background behind a skin with some level of transparency set will be "blurred". This effect uses the built-in Windows Aero effects, including changing colors to match your personalization settings for the Windows theme color.

Users on Windows XP or those with Aero or transparency in Aero turned off will see no effect from this functionality. These options must be in the [Rainmeter] section of the skin.

Options

Bangs

Example Skin


Skins-DynamicVariables


By setting DynamicVariables=1 in a measure or meter, variables that have had their values changed by the "!SetVariable" !bang can be read by that measure or meter. Additionally, if dynamic variables are turned on, a measure's name can be used as a variable to use its current value elsewhere. Measure values are encased by [square brackets]. Dynamic Variables can be used in any measure or meter, but not in the [Rainmeter] or [Variables] sections.

Note: There is also currently no support for Dynamic Variables in plugins, such as WebParser or QuotePlugin.

Example:

[Rainmeter]
Update=1000

[Variables]
Width=100

[MeasureCalc]
Measure=Calc
Formula=Counter%100

[Square1]
Meter=Image
SolidColor=255,0,0
W=#Width#
H=50
MouseOverAction=!SetVariable Width 200
DynamicVariables=1

[Square2]
Meter=Image
SolidColor=0,0,255
W=[MeasureCalc]
H=50
Y=R
DynamicVariables=1

In this example, Square1 would show a red 100x50 pixel box. When the mouse is place over the box, it grows to 200x50 as the variable is changed. Square2 shows a blue box that is 50 pixels tall and continuously grows from 0 to 100 pixels wide as it gets its width from the value of MeasureCalc.

Skins-Include

Loads an external file in the .ini format so an author can have skin, config, suite or Rainmeter-wide variables, or even shared measures. The loaded file is treated as if the contents were included in the actual skin .ini file. The path used is relative to the current .ini file.
The @include statement must be used under some section (i.e. it cannot be the first thing in the file). Most often it is used in the [Variables] section of a skin, to allow sharing of common variables between skins. If there are multiple included files within the same section of the .ini file, each @include statement should be numbered as follows: 

@include1=...
@include2=...
@include3=...
Remember that since the included file is being treated as part of the .ini file, it must also have the proper .ini formatting (i.e. [section] parameter=value). If the included file is not itself a fully working skin, then it should not use the .ini extension. Doing so may cause issues with Rainmeter's context menu, as well as some third-party applications. A common alternative is the .inc extension

The included file is read at the position where the @include is defined so the values from the included file with the same name as those from the .ini file will overwrite the values from previous sections and vice versa.

Note: You may use a variable as the name of an @include file, but not a dynamic variable.

Example:
IncludeFile.inc: 

[Variables]
Color=255,255,255,255

Skin.ini: 
[Variables]
Font=Arial
@Include=IncludeFile.inc

[SomeMeter]
FontFace=#Font#
FontColor=#Color#

Skins-MeterMeasureGroups

Measures and meters can be categorized into groups. To add a measure or meter to a group, simply add the Group= statement to the section. Any number of groups may be added to a section, all of which must be separated by a vertical bar (i.e. "|"). These groups can then be controlled through a variety of bangs.


Example:
In this example, both of the meters belong to the "CPU" group. Then, MeterCPUText also belongs to the "Strings" group and MeterCPUBar in turn belongs to the "Bars" group.
[MeterCPUText]
Meter=String
MeasureName=MeasureCPU
Group=CPU | Strings

[MeterCPUBar]
Meter=Bar
MeasureName=MeasureCPU
Group=CPU | Bars
Meters in the CPU group, for example, can be hidden as follows: !HideMeterGroup CPU

Measures

Measures are sections that determine what information Rainmeter should retrieve. Within a .ini file, names for measures must be unique and they must not have spaces. The meters use these section names to bind to the measures and display the results.

Note: Some meters require a range of values (BAR, HISTOGRAM, etc) so that they can display the measured value as relative to the minimum and maximum values. Not all measures are able to calculate the minimum and maximum value automatically so you need to do that manually with MinValue and MaxValue.

Measures-GeneralSettings

These general settings apply to all measure types.

Options

Measures-IfActions

Measure IfActions are commands you add to a measure to have Rainmeter take some action when a defined "above/equal/below" threshold value is returned by the measure. You can have Rainmeter run a built-in !Bang, several !Bangs at once, or even execute some external command.

How an action is formatted varies somewhat depending on which !Bang is being used, or what an external application expects. The rules can be found at the Bangs page.

Options

Example Skin

Measures-Calc

The Calc measure is used to calculate formulas.

Options

Operators

Logical Operators

Functions

Constants

Conditional Operator

<condition> ? <expr. if true.> : <expr. if false.>
This will evaluate condition as being either true or false. If it is true, the expression to the left of the colon (:) is evaluated. If it is false, the expression to the right is evaluated. This is equivalent to the following if-then-else statement:

   if (condition)
     then
       expr. if true
     else
       expr. if false
   end if

Random Function

The word RANDOM returns a random number between the values of "LowBound" and "HighBound" defined in the measure.

Other Bases

The Calc measure allows numbers to be represented numbering systems other than decimal. To use another base, prefix the number with a zero then the letter representing the system you wish to use. The following are accepted prefixes, which are case (lower) sensitive:
Example skin

Measures-CPU

Returns the percentage used of the entire CPU or individual cores.

Options

Example Skin

Measures-FreeDiskSpace

FreeDiskSpace returns usage statistics for the selected drive.

Options

Example Skin

Measures-Memory

Measures the amount of virtual memory free in bytes. Virtual memory is equal to Pagefile + RAM + RAM.

Options

Example Skin

Measures-NetInOut

Measures various types of network traffic.

NetIn

Measures incoming network traffic.

NetOut

Measures outgoing network traffic.

NetTotal

Measures total network traffic.

Example Skin

Measures-PhysicalMemory

Measures the amount of physical RAM memory free in bytes.

Options

Example Skin

Measures-Plugin

A plugin in Rainmeter is a dynamic link library (.dll) program specifically written to provide additional functionality not built into Rainmeter. A plugin is used in Rainmeter with the specific measure type Measure=Plugin. Each plugin in turn has its own settings that must be placed in this section. See Plugins to learn more on the plugins included with Rainmeter and what settings are required for each.

You may also use a 3rd-party plugin developed for Rainmeter but not included with the installation. Simply place the new plugin .dll file into the Plugins folder under the location of your Rainmeter.exe and the new plugin can be used like any of the default ones. Note: Be sure that the 3rd-party plugin you add was compiled for the same architecture version of Rainmeter (32bit or 64bit) as the version you are using. You may not use a 32bit plugin with 64bit Rainmeter or a 64bit plugin with 32bit Rainmeter.

Options

Example Skin

Measures-Registry

Provides a way to read data from the Windows Registry.

Options

Registry data types

If you open Regedit.exe to the location you are trying to read, you will notice the second column in the right pane is called "Type". There are several different types, but the two most common - and the two supported by Rainmeter - are REG_SZ and REG_DWORD. If the value is of type REG_SZ it means it is a string. If it is REG_DWORD it is a number. Many of Rainmeter's meter types require a number as input rather than a string. This means that if the value you are trying to read is of type REG_SZ, meters like Line, Histogram, Bar, etc. will not recognize the value. Even if the value is entirely numeric, it will still be read as a string.

Numeric string values from the registry can be used as a number if you convert them with a Measure=Calc.

[MeasureRegistry]
Measure=Registry
...

[MeasureStringToNum]
Measure=Calc
Formula=[MeasureRegistry]
MinValue=0
MaxValue=100
DynamicVariables=1

Example Skin

Measures-Script

The Script measure allows the execution of Lua (a scripting lanague) code. The Lua script can be used to retrieve the values of measures, send bangs, and more. A Lua script can do programming that would be difficult or impossible in native Rainmeter code, and can return values or change settings in the Rainmeter skin.

Options

Bangs

The Script measure can be controlled with the !CommandMeasure bang. The argument must be valid Lua code and will be executed in the context of ScriptFile.

A full explanation of how to use this measure type with the Lua scripting language can be found at Lua Scripting. This guide should be carefully read before creating a skin using the Script measure.

Measures-SwapMemory

Measures the amount of virtual (swap) memory free in bytes.

Options

Example Skin

Measures-Time

Measures the current time/date.

Options

Format codes

Full details on Time/Date formatting codes can be found at msdn.microsoft.com.

%a - Abbreviated weekday name
%A - Full weekday name
%b - Abbreviated month name
%B - Full month name
%c - Date and time representation appropriate for locale
%d - Day of month as decimal number (01 - 31)
%H - Hour in 24-hour format (00 - 23)
%I - Hour in 12-hour format (01 - 12)
%j - Day of year as decimal number (001 - 366)
%m - Month as decimal number (01 - 12)
%M - Minute as decimal number (00 - 59)
%p - Current locale's A.M./P.M. indicator for 12-hour clock
%S - Second as decimal number (00 - 59)
%U - Week of year as decimal number, with Sunday as first day of week (00 - 53)
%w - Weekday as decimal number (0 - 6; Sunday is 0)
%W - Week of year as decimal number, with Monday as first day of week (00 - 53)
%x - Date representation for current locale
%X - Time representation for current locale
%y - Year without century, as decimal number (00 - 99)
%Y - Year with century, as decimal number
%z, %Z - Either the time-zone name or time zone abbreviation, depending on registry settings
%% - Percent sign
# - A "#" character used before a code (%#d) will removing leading zeros from the result.

Example Skin

Measures-UpTime

Returns the amount of time since the last restart of the computer.

Options

Example Skin

Meters

Meters are the sections that tell Rainmeter how to display information. Each meter needs to have a unique name, which should be put inside [Square Brackets]. It does not matter what the name is as long as there are no spaces and it is not used elsewhere within the same.ini file.

Meters by default are evaluated and displayed in the order they are in the skin .ini file. Settings like W= and H= and X= and Y= can be used to size and position meters in the context of the skin containng them. So a meter with a setting of X=0 will be positioned 0 pixels from the left edge of the skin it is in. If you drag the entire skin to another location, the meter will remain positioned 0 pixels from the left edge of the skin, irregardless of where the skin is on the screen.

There are many different types of supported meter types in Rainmeter. The manual pages for each describe them in detail, with settings specific to each type.


Example Skin

Meters-GeneralSettings

The following are setting which apply to all meter types.

Options

Meters-ColorCodes

Rainmeter uses colors in the settings of many different meters.

Color codes in Rainmeter are based on RGBA, which stands for red, green, blue, and alpha. The values can be entered either using a set of four numbers ranging from 0 to 255 in either decimal or hexadecimal form. You may leave off the alpha value, and Rainmeter will default to 255 / FF, or fully opaque.

Note: If you use an alpha of 0, then the element using the color will not only be invisible, but will not be seen by Rainmeter at all for the purpose of mouse actions. If you want a meter to be invisible but still seen by Rainmeter, use an alpha of 1.

A online color picking tool which will provide the RGB and HEX codes for a color can be found at Rainmeter Color Picker.

Examples

Solid opaque red is 255,0,0,255 or FF0000FF
Solid opaque blue is 0,0,255,255 or 0000FFFF
Solid opaque grey is 128,128,128,255 or 808080FF
Half-transparent green is 0,255,0,128 or 00FF0080

Meters-MeterStyle

MeterStyles allow CSS-like common "styles" for meters. This allows you to centralize common parameters for meter into a single section. Using the MeterStyle option will essentially cause the specific meter to inherit all applicable properties from the given style. A style is just another section (it can even be a meter). Multiple styles can be used by separating them with a pipe (i.e. Style1 | Style2 | ...).

Note: You may not "daisy chain" MeterStyles. In other words although a meter may be used as a MeterStyle for another meter, that second one may not be used as a MeterStyle for a third.


Example Skin

Meters-ANoteOnFonts

Fonts are used in String meters through the FontFace option. Fonts can either be installed directly into Windows (allowing the font to be available to all installed programs) or you can use the LocalFont option (under the [Rainmeter] section) to restrict the font to Rainmeter only (and not require a separate install).

Using fonts

Installing fonts

Install the font by right clicking it and selecting "Install Font". This will install the font in Windows\Fonts and it will be available in Rainmter and all other Windows applications.

Note: Rainmeter must be restarted after installing fonts in order for Rainmeter to detect the change.

Use the font with the Family Name in a Meter=STRING meter.

[MeterName]
Meter=String
FontFace=MyInstalledFont

Using LocalFont

Place the actual .ttf font file in a folder. Use the LocalFont="Path\FileName.ttf" option in the [Rainmeter] section of your skin. Then use the Family Name in FontFace=xxx as normal.

Note: You may use more than one LocalFont in [Rainmeter] by simply adding a number: LocalFont2, LocalFont3, ...

[Rainmeter]
LocalFont="#CURRENTPATH#SomeFont.ttf

[MeterName]
Meter=String
FontFace=MyLocalFont

Example Skin

Meters-ToolTips

This creates a ToolTip which appears when you hover the mouse over the meter. You must be careful not to overlap two meters with ToolTips as both will be displayed if the mouse is over both at the same time.

Options

Meters-TransformationMaxtrix

This defines a 3x2 matrix which can be used to transform the meter. There must be exactly 6 values separated by semicolons (e.g. TransformationMatrix=1;0;0;1;0;0). The values a;b;c;d;e;f correspond to the following matrix: 
|a c e|
|b d f|
In short, the values have the following effects: Combining these can have drastic effects on the meter it is applied to. For more comprehensivev information on TransformationMatrix, read this forum thread. The following are some examples showing the actual matrix and the corresponding TransformationMatrix values:

Flip X along line x=20:
|-1 0 2x|   |-1 0 40|
| 0 1 0 | = | 0 1 0 |
TransformationMatrix=-1;0;0;1;40;0

Flip Y along line y=50:
|1  0 0  |   |1  0 0  |
|0 -1 2*y| = |0 -1 100|
TransformationMatrix=1;0;0;-1;0;100

Scale X by 0.5 (at x=50):
|0.5 0 0.5*x|   |0.5 0 25|
|0   1 0    | = |0   1 0 |
TransformationMatrix=0.5;0;0;1;25;0

Note: All transformations are relative to the top left corner of the window and not to the meter itself. So if you want to rotate the meter by its center the translation component in the matrix must be relative to the top left corner of the window.

Also note that the even if the meter's visual location and orientation is changed by the transformation the place where it would be located without the transformation will still be used to define the window size and register the mouse clicks. This might change in the future though.

Meter-Bar

Bar meters display the value of a measure in a single vertical or horizontal bar. The amount the bar is filled corresponds to the relative value of the measure. Bar graphs require that the measure being used is from 0.0 to 1.0 or has both MaxValue and MinValue set.

Changes to the bitmap are applied in the following order: ImageCrop -> GreyScale -> ImageTint -> ImageFlip -> ImageRotate.

Options

Example Skin

Meter-Bitmap

The Bitmap meter takes an image and divides it into equally-sized frames. Each frame is shown as the relative value of the measure attached to it reaches the relative position of the pieces. For example, if the image a strip of 5 images, when the measure is between 0% and 19% the first frame is shown, from 20 to 39% the second frame is show, and so on. Bitmaps are often used with counters to display animations, or are used to show stylized numbers.

Changes to the bitmap are applied in the following order: GreyScale -> ImageTint -> ImageFlip.

Options

Example Skin

Meter-Button

The button meter cannot be bound to any measure. Its entire purpose is to make the creation of buttons easier. A button can display a normal, clicked and hover state of an image and perform an action automatically.

Changes to the button image are applied in the following order: GreyScale -> ImageTint -> ImageFlip.

Options

Example Skin

Meter-Histogram

Histograms display values using vertical bars - once per update - on a graph. They require that the measure being used ranges from 0.0 to 1.0 or has both MaxValue and MinValue set.

Changes to the images are applied in the following order: ImageCrop -> GreyScale -> ImageTint -> ImageFlip -> ImageRotate.

Options

Example Skin

Meter-Image

The Image meter is used to show images. It does not necessarily need to be tied to a measure and is often used just to display a specific image for aesthetic purposes. However, when used with a measure, it will try to display the image whose filename corresponds to the value of the measure.

Changes to the image are done by applied in the following order: ImageCrop -> GreyScale -> ImageTint -> ImageFlip -> ImageRotate.

Options

Example Skin

Meter-Line

The line meter shows the values of a measure as a graph with a line connecting each data point. Any number of lines can be shown depicting as many measures with a single meter, all overlapping. Line meters require that the measure being used is from 0.0 to 1.0 or has both MaxValue and MinValue set.

Options

Example Skin

Meter-Rotator

The rotator meter displays an image that rotates around a point where the angle of rotation is determined by the measure it is attached to. Rotator meters require that the measure being used is from 0.0 to 1.0 or has both MaxValue and MinValue set.

Changes to the image are done by applied in the following order: ImageCrop -> GreyScale -> ImageTint -> ImageFlip -> ImageRotate.

Options

Example Skin

Meter-Roundline

The roundline meter displays a single line that rotates around a point. The angle of the line is determined by the measure. By default, the minimum position is pointing to the right, the line then moves clockwise until it is pointing to the right again. If the width and height are not defined, the center point is the at the X and Y position of the meter. If width and height are specified, it is in the middle of the bounding box. Roundline meters require that the measure being used is from 0.0 to 1.0 or has both MaxValue and MinValue set.

Options

Example Skin

Meter-String

String meters display the value of measures as text. A string meter does not necessarily need to have a measure attached to it and can just be a static string of text by using Text=. You can mix the results of measures and static text by using Text= combined with %1, %2 etc. to indicate the value of the measures used by the meter. If you are only displaying the result of a single measure, no Text= statement is needed.

Options

Example Skin

Plugins

A plugin in Rainmeter is a dynamic link library (.dll) program specifically written to provide additional functionality not built into Rainmeter. A plugin is used in Rainmeter with the specific measure type Measure=Plugin. Each plugin in turn has its own settings that must be placed in this section. Click on any of the plugins listed on the right to learn more about the plugins included with Rainmeter and what settings are required for each.

You may also use a 3rd-party plugin developed for Rainmeter but not included with the installation. Simply place the new plugin .dll file into the Plugins folder under the location of your Rainmeter.exe and the new plugin can be used like any of the default ones. Note: Be sure that the 3rd-party plugin you add was compiled for the same architecture version of Rainmeter (32bit or 64bit) as the version you are using. You may not use a 32bit plugin with 64bit Rainmeter or a 64bit plugin with 32bit Rainmeter.

If you are interested in creating a 3rd party plugin for Rainmeter, there are source code templates available for both C++ and C# coders. Further information can be found at Developers.

Plugin-AdvancedCPU

Plugin=AdvancedCPU

This is similar to using PerfMon to measure the CPU usage except that you can filter out processes or only include some of them.

Options

Example Skin

Plugin-CoreTemp

Plugin=CoreTemp

This plugin can retrieve the values measured by CoreTemp. CoreTemp must be running in the background in order for the plugin to work. A list of supported CPU's is available here.

Options

Example Skin

Plugin-FolderInfo

Plugin=FolderInfo

FolderInfo.dll can be used to count files in a folder, their size, and more.

Options

Example Skin

Plugin-InputText

Plugin=InputText

InputText inserts user-supplied text into a one or more bangs. The plugin works by defining a series of commands, which can be triggered by any "action" string (this includes mouse actions, conditional actions in a Calc measure, and other commands in an InputText measure, including the same measure). When triggered, a free-floating text input box is created to gather user input at the specified points in the command series. When all input has been submitted, the commands are carried out.

Options

Bangs

LeftMouseUpAction=!CommandMeasure "MeasureInputTextPlugin" "ExecuteBatch ALL X=100"
IfAboveAction=!CommandMeasure "MeasureInputTextPlugin" "ExecuteBatch 3"
Command4=!CommandMeasure "MeasureInputTextPlugin" "ExecuteBatch 2-4 Password=1"

Notes: Example Skin

Plugin-iTunes

Plugin=iTunesPlugin

This plugin can be used to remote control iTunes and get information from it.

Note: New skins should use the NowPlaying plugin as it supports multiple media players (including iTunes).

Options

Bangs

iTunes can be controlled through !CommandMeasure statements. You can either one of the following methods.

The example skin below demonstrates both methods.

Example Skin

Plugin-NowPlaying

Plugin=NowPlaying

The NowPlaying plugin is used to control various media players and retrieve track metadata (including album art) from them.

IMPORTANT: This plugin uses the the concept of 'main' and 'secondary' measures. To understand the difference, refer to the example skin at the end of this page.

Options

Bangs

The media player can be controlled with !CommandMeasure statements. See the sample example skin below for usage.

Supported Players

This list contains all supported media players in the latest beta version of Rainmeter. Note that using an unsupported type or bang is perfectly safe (it will simply result in in a empty value or no action, respectively).

Other Players

In addition to the players listed above, the NowPlaying plugin may support other players through supported interfaces. You may want to give the following interfaces a try.

If none of these work, leave a suggestion in this thread. If you're nice enough, support for your player will be added shortly after your message :-)


Example Skin

Plugin-PerfMon

Plugin=PerfMon

Use Window's Performance Monitor to find out the valid values for these settings. There are a great many counters which Windows tracks in Performance Monitor. From the Start Menu, type "Perfmon.msc" to run the tool and find the counters you wish to measure.

Note: The names of the objects, counters and instances need to be in English even in localized versions of Windows.

Options

Example Skin

Plugin-PingPlugin

Plugin=PingPlugin

This plugin can be used to send ping packets to a server and measure the network latency.

Options

Example Skin

Plugin-PluginMediaKey

Plugin=MediaKey

The MediaKey plugin allows you to send various keystrokes found on multimedia keyboards. It has been tested to work with Spotify, Zune, foobar, and Windows Media Player.

Usage:

[MeasureMediaKey]
Measure=Plugin
Plugin=MediaKey

The plugin is controlled via !CommandMeasure statements sent to its measure. E.g.:

!CommandMeasure "MeasureMediaKey" "NextTrack"

Valid arguments are:

Plugin-PowerPlugin

Plugin=PowerPlugin

This plugin can be used to measure battery status and the current MHz on laptops. Note that not all laptops support this (or all the values).

Plugin-Process

Plugin=Process

Detects if a defined Windows process or application is currently running.

Options

Returns values of -1 (not running) or 1 (running).

Note: This can not be used to detect if a Windows "service" executable is running, as those processes are run inside of the "svchost.exe" process.


Example Skin

Plugin-Quote

Plugin=QuotePlugin

This plugin has two different uses: it can display a random string from a text file or it can select a random file from a folder which can be displayed with the IMAGE meter (if it's an image that is).

Options

Example Skin

Plugin-RecycleManager

Plugin=RecycleManager

This plugin can be used to check the size and count of the files in the recycle bin.

Options

Bangs

The following bangs can also be sent to any RecyleManager measure:

Example Skin

Plugin-ResMon

Plugin=ResMon

Requires Windows XP with Service Pack 1 or newer. The plugin was originally made by Daedalus.

Options

Plugin-Speedfan

Plugin=SpeedFanPlugin

This plugin can read the values measured by SpeedFan. You need to have SpeedFan running for this plugin to work since it doesn't do any measuring itself.

Options

Plugin-SysInfo

Plugin=SysInfo

This plugin returns various information about your system.

Options

Plugin-VirtualDesktops

Plugin=VirtualDesktops

A virtual desktop manager (VDM) allows you to distribute programs across multiple desktops. The VirtualDesktops plugin gives access to information from different VDMs for Windows and can be used to trigger desktop switches.

General Options

Options for VDManager=Dexpot

Note that bangs do not default to the current skin (use !Refresh "#CURRENTCONFIG#" instead of just !Refresh, for example).

Additional types for VDMeasureType:

Other options specific to VDMeasureType=Screenshot:

Plugin-WebParser

Plugin=WebParser

WebParser reads information from webpages. The plugin uses Regular Expressions to parse the web page which allows it to extract information pretty much from any page. The plugin can be used e.g. to get the current TV shows, weather conditions, stock exchange values, news and basically anything that is on the net. The negative side is that the regular expressions might look rather complex especially if you're not familiar with programming languages (and even if you are :-).

More information and examples for WebParser can be found at WebParser Primer and RSS Skin Tutorial.

Options

Examples:

Retrieve the title and first item from Slashdot's RSS feed.

[MeasureRSSTitle]
Measure=Plugin
Plugin=WebParser
UpdateRate=3600
Url=http://slashdot.org/slashdot.rdf
RegExp="(?siU)<title>(.+)</title>(.+)<item(.+)<title>(.+)</title>"
StringIndex=1
FinishAction=!Redraw

[MeasureRSS]
Measure=Plugin
Plugin=WebParser
Url=[MeasureRSSTitle]
StringIndex=4
Substitute="&amp;":"&"

Download the current weather map from Finnish Meteorological Institute.

[MeasureDL]
Measure=Plugin
Plugin=WebParser
UpdateRate=1800
Url=http://www.fmi.fi/saa/sadejapi_5.html?selected=7
RegExp="(?siU)ennuste" SRC=\"(.*)\"></TD>"
FinishAction=!Redraw
StringIndex=1
Download=1

[MeterImage]
Meter=IMAGE
MeasureName=MeasureDL
X=0
Y=0
W=400
H=300

Plugin-WiFiStatus

Plugin=WiFiStatus

The WiFiStatus plugin can be used to display various attributes of visible wireless networks in your area. Windows XP SP2 users need to install the KB918977 hotfix.

Options

Examples: 

[MeasureSSID]
Measure=Plugin
Plugin=WiFiStatus
WiFiInfoType=SSID
WiFiIntfID=0

[MeasureNetworks]
Measure=Plugin
Plugin=WiFiStatus
WiFiInfoType=LIST
WiFiIntfID=0
WiFiListStyle=3

A more detailed sample and support is available at the WiFiStatus support thread.

Plugin-Win7AudioPlugin

Plugin=Win7AudioPlugin

Controls sound device and volume for Windows Vista and newer. Previous versions of Windows are not supported. This plugin has been written by Reiswaffel.

Usage

[MeasureWin7Audio]
Measure=Plugin
Plugin=Win7AudioPlugin

Returns the name of the current sound device (when used in a STRING meter) and the percentage (0-100) of current volume level (when used in a measure which requires a number).

Bangs

The current device and volume is controlled with !CommandMeasure statements sent to the plugin. See the sample .ini below for examples.


Example Skin

Plugin-WindowMessage

Plugin=WindowMessagePlugin

This plugin can be used to send and receive information from other applications. It can send window messages to other applications and show the result. The plugin can be used for example to control WinAmp or some similar media players.

Options

Bangs

Messages can also be sent on demand with the !CommandMeasure bang. The arguments are similar that of the WindowMessage option.
!CommandMeasure "MeasureName" "SendMessage Msg wParam lParam"


Examples:

This returns the name of the song that is playing in WinAmp.

[MeasureWinamp]
Measure=Plugin
Plugin=WindowMessagePlugin
WindowClass=Winamp v1.x
Substitute="[Paused]":""," - Winamp":""

Check if Winamp is playing, or not. This returns 0 if it's not playing, 1 if it is playing and 3 if it's paused.

[MeasureWinampPlaying]
Measure=Plugin
Plugin=WindowMessagePlugin
WindowClass=Winamp v1.x
WindowMessage=1024 0 104

Show song progress. The  [MeasureWinampDuration] will return the current song position as a value between 0 and 1. You can use for example the BAR-meter to display the value.

[MeasureWinampFull]
Measure=Plugin
Plugin=WindowMessagePlugin
WindowClass=Winamp v1.x
WindowMessage=1024 1 105

[MeasureWinampCurr]
Measure=Plugin
Plugin=WindowMessagePlugin
WindowClass=Winamp v1.x
WindowMessage=1024 0 105
[MeasureWinampDuration]
Measure=Calc
Formula=(MeasureWinampCurr<=0)?0:(MeasureWinampCurr/(MeasureWinampFull*1000+1))

MouseActions

Mouse actions are commands you add to a meter or the [Rainmeter] section to execute an action on a specific mouse event.

Note: When using a mouse action on a string meter or image meter with transparency, you must click exactly on the meter text or image, as the transparent areas do not react to clicks. This can be solved by adding SolidColor=0,0,0,1 to the meter, which will create an near-invisible but solid background behind the meter element.

Also note that actions defined for the meter will override actions defined in the [Rainmeter] section.

Bangs

Rainmeter can also be controlled with !Bang-commands. A bang is a special command that can be executed to change something in the application. You can use the bangs in the various actions that Rainmeter has, or run from them from the command line by giving it as an argument for Rainmeter.exe.

General Rules

Bangs

Note that the [] means that you must supply the argument for the bang (do not include the []-chars). The () means that the argument is optional.

Most !bangs take also the config as an optional parameter. If the config is defined the bang only applies to that particular config. If it's not given, the !bang is sent to the current (in a skin) or first (from the command line) config. Use * as the config's name to send it to all configs.

Actions for the Rainmeter application

Actions for variables and settings in skins or groups of skins

Actions for a skin or group of skins

Actions for a meter or group of meters

Actions for a measure or group of measures

LuaScripting

Rainmeter, nor anyone associated with Rainmeter, is responsible for teaching you the Lua scripting language. This guide is only meant to help with using Lua with Rainmeter. However, Lua is a relatively simple language, and there are many good sites where you can learn Lua itself:

http://www.lua.org/manual/5.1/
http://lua-users.org/wiki/LuaTutorial

Or a really good book for sale:
Programming Lua Second Edition

Overview

A Lua scripting language file (.lua) can be executed by Rainmeter, passing settings from Rainmeter to the script. The script can then be used to read Rainmeter measures and meters from the calling skin, do any kind of processing outside of Rainmeter that you like, and take various actions that impact the Rainmeter skin:

Rainmeter has the Lua 5.1 codebase embedded. It contains all the standard libraries and functions that come with Lua, but currently cannot be extended by using external libraries like LuaCURL in your code or "including" external script files using "dofile". This is due both to the need to protect the Rainmeter core in memory, and to limitations of Lua external libraries in a 32bit / 64bit environment. Improvements to this may come at a later date.

In the Skin

Lua is integrated with Rainmeter using the new Rainmeter Measure=Script measure type:

[MeasureLuaScript]
Measure=Script
ScriptFile=MyScript.lua
MySetting="SomeSetting"
UpdateDivider=30

ScriptFile= This is the required name of the .lua file you will be executing.
MySetting= This is just a sample to show how you can pass information to the Lua script from Rainmeter when it is run. This can be any key name and any value, and you can have none, or as many as you like.
UpdateDivider= This optionally tells Rainmeter how often to execute the script, as with any other Rainmeter measure.

Notes:

In the Script

There are three functions in a .lua script file written for Rainmeter that control the overall interaction with Rainmeter:

PROPERTIES
This is actually a Lua "table", used to hold the settings (Key=Value, like MySetting="SomeSetting" in the example above) you wish to pass from Rainmeter to the Lua script. You simply tell it the name of the key from the measure in the skin, and initialize it with any value. The format is:
PROPERTIES =
{

  MyTextSetting = "";
  MyNumberSetting = 0;
}

You can then later use these settings in your script, with PROPERTIES.MyTextSetting for example, a standard Lua way of reference a table index by value. Remember that Lua is always "case sensitive". This table is PROPERTIES, not Properties.

function Initialize()
This function is used to perform actions you wish to do "once" when the skin is loaded or refreshed. It can be used to have the script get the structures of measures and meters in the skin so you can interact with them later, initialize global variables, tables etc. you will use later, or even take actions on the skin that you only want to happen once. For instance:
function Initialize()
  Measure1 = SKIN:GetMeasure("SomeMeasure")
  Meter1 = SKIN:GetMeter("SomeMeter")
  CurrentMeter1Height = Meter1:GetH()
  Meter1:Hide()

  MyNewVar = PROPERTIES.MyTextSetting
  MyNewTable = {}
end

function Update()
The Update() function is where you will put the bulk of your code. It is executed on every update cycle of the measure and should return either a string or a number, which will be used as the value of the SCRIPT measure. For the purpose of this example, lets assume that your Script measure is called MeasureScript. Example:
function Update()
  SomeNewVar = "Hello World"
  SKIN:Bang(!SetVariable MyVar "..SomeNewVar)
  NewReturnValue = 99

  return NewReturnValue
end

Simple Example:

Skin:
[Rainmeter]
Update=1000

[MeasureLuaScript]
Measure=Script
ScriptFile="#CURRENTPATH#LuaSample.lua"
SettingInSkin=20

[MeterLua]
Meter=String
MeasureName=MeasureLuaScript
FontSize=12
FontColor=255,255,255,255

Script:
PROPERTIES =
{
  SettingInSkin = 0;
}

function Initialize()
  CurrentNumber = tonumber(PROPERTIES.SettingInSkin)
end

function Update()
  NewNumber = CurrentNumber + 50
  return NewNumber
end

The measure [MeasureLuaScript] in the skin will have a string value of "70", which can be used in any calc or meter.

Functions

There are several Rainmeter-specific functions exposed to Lua. Functions may return a string (e.g. "example"), a number (e.g. 42), a boolean value (i.e. true or false), or nothing (marked by void).

print()
Allows you to output text to the Rainmeter log. Note that if the Lua interpreter raises an error in your Lua code in general, it will automatically be written to the Rainmeter log and can be viewed using "About" from the Rainmeter context menu.
print("Script just ran!")

Skin functions

These functions can be used on used with the SKIN: prefix. For example:

meter = SKIN:GetMeter("ExampleMeter")
SKIN:Bang("!Refresh")

Meter functions

These functions can be used on meter objects returned by the SKIN:GetMeter() call. For example:

anyMeter = SKIN:GetMeter("ExampleMeter")
anyMeter:SetX(25)

Measure functions

These functions can be used on objects returned by the SKIN:GetMeasure() call. For example:

anyMeasure = SKIN:GetMeasure("ExampleMeasure")
anyMeasure:Disable()

Deprecated Functions

These are functions that should not be used. They are supported for now and may be removed in the future.

Executing Lua code within Rainmeter

The !CommandMeasure bang can be used to execute Lua code in Rainmeter.

LeftMouseUpAction=!Execute [!CommandMeasure "ScriptMeasure" "someVar=5;someVar2=someVar*7;Update()"]
-> set variable someVar to 5, set a new variable with a formula, and immediately execute the Update function. (in the context of the ScriptFile specified by ScriptMeasure)

Example Skins

There are some simple skins using the new Lua integration on the Rainmeter forums. Tearing them apart can be the best way to learn how it all fits together:

http://rainmeter.net/forum/viewtopic.php?f=99&t=9131
http://rainmeter.net/forum/viewtopic.php?f=27&t=6658
http://rainmeter.net/forum/viewtopic.php?f=27&t=6533
http://rainmeter.net/forum/viewtopic.php?f=27&t=9388

RMSkinCreate

The Rainmeter skin package (.rmskin) is an increasingly popular method of distributing various Rainmeter components. It allows one-click installation of skins, themes, fonts, and more.

To create a .rmskin package, get the .rmskin template from here, then extract and open the newly created Template folder. It should contain five folders along with a file called Rainstaller.cfg.

Adding your skins / themes / addons / plugins and fonts.

To add components to the package, simply copy it into the correct folder.

For example, to include the "MySkins" suite of skins, simply copy the entire Documents\Rainmeter\Skins\MySkins folder from your Rainmeter installation into Template\Skins in the template folders.

More on including plugins

You are able to include both 64bit and 32bit in one single .rmskin. If you decide to take advantage of this, you must specify at least MinRainmeterVer=2.0.0.740 into Rainstaller.cfg. Then, create the Template\Plugins\32bit and Template\Plugins\64bit folders and copy the plugin(s) into the appropriate folder.

Template\
- Plugins\
-- 32bit\
--- myplugin.dll
-- 64bit\
--- myplugin.dll

More on including Fonts

There are three ways to include font(s) in your distribution:

Changing settings

After you have copied all the necessary files into the correct folders, open any text editor (e.g. notepad) and drag & drop the Template\Rainstaller.cfg file into the text editor. Fill in the obvious (Name, Author, and Version) and save the file. A detailed explanation of the other values is available at the end of this page, be sure to glance through that list.

Creating the .rmskin file

The .rmskin file is simply a renamed .zip file. So, in order to create a .rmskin file, you'll need to create a .zip file first. To do this, right-click on the Template folder and select Send to -> Compressed (zipped) folder. You will be asked to name the newly created .zip file. Give it the name of your choice and press Enter.

To convert the created .zip file into a .rmskin file, simply change the file extension from .zip to .rmskin. If you don't know how to do this manually, grab and run ExttensionChanger from from here. It will allow you change extensions from .zip to .rmskin and vice versa.

Testing and sharing

Before sharing the newly created .rmskin with others, you will need to make sure it works properly. Remember to delete the components from your own computer before installing to make sure the files were installed properly. For example, if you know that the .rmskin is going to install a skin called "BestSkinEver", delete "BestSkinEver" from Rainmeter\Skins.

After you have ensured that everything works as intended, you are free to upload and share your .rmskin with others.