Measures

A measure is an object that retrieves information to be used by the skin. Measures are one of the two major kinds of objects in a skin, along with meters.

Usage

Unlike meters, measures do not display anything by themselves. You cannot "see" a measure in a skin. The measure simply provides the information as a value, which can be used in several ways:

  • A meter can be bound to a measure. In this way, the meter will automatically display the value in a way that is appropriate for the type of meter. This also takes the measure's range and scale into account (if applicable).

  • The measure value can be referenced as a section variable. In this way, the value can be used in almost any meter or measure option. As a section variable, the value is used "literally," which means it does not automatically account for the range or scale.

  • A measure can trigger an action when the value passes into a certain range.

Some measure types may have their own special rules. These are detailed in their individual articles.

Format

A measure is written as a section in the skin. All measures use the Measure option to define the section as a specific type of measure. Most other measure options depend on the type, but there are some general options that are valid in many or all measures.

Below is an example of a complete working measure:

[MeasureFour]
Measure=Calc
Formula=2+2
UpdateDivider=-1

Values

A measure actually provides two values: a string, or "raw text," and a number, which can be used in calculation formulas. Depending on the type of measure, these values may be the same, which means you can use them interchangeably; or, they may be completely different. The article for each measure type explains what is provided for both the number and string values.

  • When a meter is bound to a measure, it automatically uses the correct value for its type.

  • When using Section Variables, different syntax is used to refer to a measure's string or number value.

  • The Substitute option affects only the string value of the current measure.

  • IfAction options use only the number value of the current measure.

  • The Formula option in a Calc measure uses only the number values of other measures, unless section variables are used instead.

Although a string value is not a "true" number, it can be used like a number in formulas and options, as long as it contains only numeric characters and valid operators. (Otherwise, it is treated as zero.) Likewise, a number value can be displayed or stored to a variable as a string of text, although this may cause the value to lose precision.

Percentage

Some meters require that a measure provide a value that can be used as a percentage. These would include Bar, Histogram, Line, Rotator and Roundline meters. In order for these meters to know that the current value of the measure is 27%, they need to know what value 100% represents. In addition, you may want to display the percentage of the total value a measure is currently at in a String meter, or use the percentage value of a measure in a formula.

The percentage of the total that a measure's current value reflects is based on the "range" that the measure can be. This is defined as the MinValue and MaxValue of the measure.

Some measures, for example CPU, FreeDiskSpace and Memory, automatically set the minimum and maximum range that the measure can be. FreeDiskSpace for instance knows how big the drive you are measuring is, and will set the MinValue to zero, and the MaxValue to the actual size of the drive. Then you can just use the measure's value in a meter by binding the measure to it with MeasureName=MyMeasure and the percentage will be used in the display of the meter. There is nothing you need to do for this to work properly.

Other measures do not know themselves what the maximum value the measure can be. Examples of this are the NetIn/NetOut/NetTotal measures, SpeedFan, any Calc measures, and any WebParser measures. What Rainmeter will do in this case is to set the MinValue and MaxValue of the measure dynamically, to the smallest and largest values the measure has been since the skin was loaded or refreshed. This may not always be the behavior you desire.

To address this, you can manually define the range that the measure can be, by setting the MinValue and MaxValue options on the measure. Remember, you set this on the measure you are going to use as a percentage, not on the meter that is using it.

For example:

[MeasureCPUTemp]
Measure=Plugin
Plugin=SpeedFanPlugin
SpeedFanType=TEMPERATURE
SpeedFanScale=C
SpeedFanNumber=2
MinValue=30
MaxValue=100
[MeterCPUTempBar]
Meter=Bar
MeasureName=MeasureCPUTemp

While the String meter does not require a percentage when displaying the number value of a measure, it can be told to use the value as a percentage, by using the Percentual option on the meter. The meter will then use the MinValue and MaxValue of the measure to calculate what percentage of that the current value is.

In addition, you can use the percentage value of a measure in a formula or String meter by using the measure as a Section Variable, with the percentage parameter.

Setting these options has no effect on the actual value of the measure, but only defines the low and high range, to used by meters.

Note: The current MinValue / MaxValue "range" for a measure can be viewed in the Skins tab of the About window. This can be useful for debugging problems when you are not getting the meter output you expect.

Order

Each time the skin updates, all measures in the skin are evaluated in order. This means that if a measure references the value of another measure that has not been evaluated yet, it will receive the value from the previous update.

For example:

[MeasureCounterPlusOne]
Measure=Calc
Formula=MeasureCounter + 1
[MeasureCounter]
Measure=Calc
Formula=Counter

The intent is for [MeasureCounterPlusOne] to add one to the value of [MeasureCounter], so that it is always greater than [MeasureCounter]. If the measures were in the opposite order, this would work. However, because [MeasureCounterPlusOne] is evaluated before [MeasureCounter], it will only add to the old, "outdated" value, and the two measures will remain equal.