String meter

Meter=String displays text.

Options

General meter options

All general meter options are valid.

MeasureName, MeasureName2, ..., MeasureNameN

Name(s) of the measure(s) bound to the meter. The meter will display the current value of the measure defined in MeasureName, with values for additional measures bound to the meter available using the %N syntax in the Text option.

The meter does not require a MeasureNameN option if the Text option alone will be used to define the string to display.

Text Default: %1

Text to display. If MeasureName is specified, Text will default to the value of the measure.

The values of the measure(s) specified with MeasureName can be used with the %N syntax as follows:

MeasureName=SomeMeasure
MeasureName2=SomeMeasure2
Text=This is text containing %1 and %2.
; %1 and %2 will be replaced by the string values of SomeMeasure and
; SomeMeasure2, respectively.

The Text option can take any combination of the following forms:

  • Display the value of a measure bound with MeasureName
  • Display the values of multiple measures bound with MeasureNameN, and formatted with the %N syntax.
  • Display static text defined in the option.
  • Display the current value of any variables or section variables. Note that the meter must contain the DynamicVariables option to use the current value of variables or measures defined as a section variable.
Prefix

Text displayed before Text.

Note: It is preferable to put the entire string in Text instead of using this option.

Postfix

Text displayed after Text.

Note: It is preferable to put the entire string in Text instead of using this option.

FontFace Default: Arial

Family name of the font to use for the text. The font must either be installed in Windows directly or must be loaded at runtime.

See also: Fonts Guide.

FontSize Default: 10

Size of the font in points. This is an integer value, with decimal values rounded down.

FontColor Default: 0,0,0,255

Color of the font.

StringAlign Default: Left

Horizontal and vertical alignment of the string. Valid values are:

  • Left, Right, Center (or LeftTop, RightTop, CenterTop)
  • LeftBottom, RightBottom, CenterBottom
  • LeftCenter, RightCenter, CenterCenter

The string will be aligned using the values of the X and or Y settings as the anchor point. So to CenterCenter align a string within a meter with a width and height of 100, set X=50, Y=50 and StringAlign=CenterCenter.

StringStyle Default: Normal

Style of the string. Valid values are Normal, Bold, Italic, and BoldItalic.

StringCase Default: None

Converts the string to a case. Valid values are None, Upper, Lower, and Proper.

StringEffect Default: None

Effect applied to a string. Valid values are None, Shadow, and Border.

FontEffectColor Default: 0,0,0,255

Color of the StringEffect.

ClipString Default: 0

Controls how strings are truncated (clipped) or wrapped to fit in or expand the containing meter. Valid values are:

  • 0: Disabled. The string will not be clipped or wrapped. (default)
  • 1: Enabled. The string will be clipped with an added ellipsis ... when it exceeds the specified W (width) option on the meter. If the H (height) option is large enough to allow multiple lines, the text is wrapped until the value of H is reached, then clipped.
  • 2: Auto. The string will be clipped or wrapped based on the value of W and/or H. If the width or height are not specified, the meter itself will change size to accommodate the string. This setting works in conjunction with the ClipStringW and ClipStringH options below, to set a "maximum" size that the meter should expand to accomodate the string before clipping.

Notes: The changing size of meters when ClipString=2 can cause truncation issues with the overall window size of the skin, unless DynamicWindowSize=1 is set in the [Rainmeter] section of the skin.

When ClipString=2 is used with bound measures that have an initial value of "", (WebParser and QuotePlugin for example) DynamicVariables=1 must be set on the meter.

ClipStringW

Sets a maximum width that the meter will expand to accommodate the string when ClipString=2. This setting is ignored if the W option is set.

ClipStringH

Sets a maximum height that the meter will expand to accommodate the string when ClipString=2. This setting is ignored if the H option is set.

Angle Default: 0.0

Defines the angle of the text in radians.

Note: The size and position of the text are always calculated as if the text is horizontal. This also means that the click-able field used for Mouse Actions does not change. It remains where the text would be with no Angle.

More information about using Angle can be found at Working with Angle on a String Meter.

Percentual Default: 0

If set to 1, the value of bound measures are converted to a percentage. This is useful if a measure does not return a percentage value, but either automatically defines a valid "range" of values (e.g. FreeDiskSpace) or when the MinValue and/or MaxValue options are manually set on the measure.

NumOfDecimals Default: 0

Number of decimals to display with numerical measure values.

Scale Default: 1

Scaling factor used for the measure values. The measure value is divided by the specified value. If the specified value has a decimal point (e.g. 1000.0), the result will also display decimals.

Note: If AutoScale is enabled, this option is ignored.

AutoScale Default: 0

Automatically scales the measure values. The scaled result is appended with k, M, G, etc. as appropriate. Valid values are:

  • 0: Disabled.
  • 1: Scales by 1024.
  • 1k: Scales by 1024 with kilo as the lowest unit.
  • 2: Scales by 1000.
  • 2k: Scales by 1000 with kilo as the lowest unit.

Note: The value returned by AutoScale adds a space between the scaled number and the scale unit abbreviation. To remove this space simply add Substitute=" ":"" to the Measure that the AutoScale is being applied to.

Note: Using the SolidColor option, with a value of SolidColor=0,0,0,1, will give a string meter a solid but virtually transparent background. This can make executing mouse actions on the text easier and more reliable.

Example

[Rainmeter]
Update=1000
AccurateText=1
DynamicWindowSize=1

[Metadata]
Name=ExampleMeterString
Author=The Rainmeter Team
Information=Example of the String meter
License=Creative Commons Attribution-Non-Commercial-Share Alike 3.0
Version=1.0

[MeasureDate]
Measure=Time
Format=%A, %b %#d, %Y

[MeterDate]
Meter=String
MeasureName=MeasureDate
X=0
Y=0
FontColor=255,255,255,255
FontFace=Segoe UI
FontSize=17
StringEffect=Shadow
FontEffectColor=0,0,0,255
AntiAlias=1
Text=Today is: %1

[MeterText1]
Meter=String
X=0
Y=0R
FontColor=197,239,252,255
FontSize=12
AntiAlias=1
Text=Relative to bottom of previous meter

[MeterText2]
Meter=String
X=300
Y=10R
W=300
H=20
StringAlign=Right
FontColor=255,255,255,255
StringStyle=Italic
FontSize=14
AntiAlias=1
Text=Right justified italic text

[MeterText3]
Meter=String
X=150
Y=5R
W=300
H=20
StringAlign=Center
FontColor=252,245,197,255
StringStyle=Bold
FontSize=14
AntiAlias=1
Text=Centered bold text

[MeterText4]
Meter=String
X=0
Y=10R
W=200
H=50
ClipString=1
FontColor=197,252,223,255
StringStyle=Bold
FontSize=14
AntiAlias=1
Text=This text will wrap due to ClipString=1

An example skin showing various string options.